Why the client needs the partner's documentation
The rollout is carried out by an authorised partner, who installs, configures and maintains the system. During an internal audit or inspection the client must be able to show how the system is set up, who has which permissions and when the rollout was accepted. Without documentation, the answer depends on the memory of a particular partner engineer.
The partner model separates the licence agreement with the manufacturer from the implementation and maintenance agreements with the partner. Documentation is therefore important also from the perspective of continuity: when the client changes partner, the new contractor takes over maintenance on the basis of what has been written down.
Scope of the documents the partner should hand over
We recommend five basic documents. Each has one purpose and can be short, as long as it is up to date.
Configuration description
It covers the settings of modules, maps, zones, permit templates and notification channels. It is good when it also describes the reasons for the choices, not only the values, because this makes later changes easier.
Roles and permissions matrix
Roles in the system and the permissions matrix let you configure access for administrators, security, OHS and the coordinators of external companies without any change to the code. The document should show which person has which role, since when and who assigned it.
Integration description
The platform offers a REST API (versions 1 and 2, JWT authentication) and webhooks to the automation platform. The document describes which client systems are connected, which events are transmitted and who owns the access key on the client side.
Acceptance protocol
Pilot acceptance is based on explicit criteria and lasts 3 to 6 months. The protocol should contain the criteria, test results, the date, the signatures of persons authorised on the client and partner sides and remarks for improvement.
Maintenance agreement and SLA
It contains reaction and repair times, availability of 99.5% and the rules for reducing the fee for overruns. Sample SLA from the draft partner agreement: category A reaction 12 hours and repair 8 hours, category B reaction the next day and repair in 1 day, category C repair within 7 days.
SLA repair time by request category
Audit trail as a supplement to the documents
Documents describe the state on the day of acceptance. The audit trail in the system records changes to selected data together with the author and the time, which gives the partner evidence of the configuration carried out at acceptance. This way, if an auditor asks a question, you can show not only the description but also the record of changes.
Take a snapshot of the configuration on the day of acceptance and attach it to the protocol. For later changes, the audit trail will show the difference from that state.
Division of responsibility in the documents
Good documentation states who is responsible for what: the manufacturer for the software and the licence, the partner for the rollout and maintenance, the client for the network and the plant's resources. If a document does not settle whom to report a given type of problem to, response time will suffer.
Add to the package a short instruction for reporting faults with categories A, B and C and the contact details of the partner's on-call staff. Keep the contact details in a separate document that the client updates when people change.
How to avoid typical gaps
The most common gaps are an outdated permissions matrix after staff changes, no description of the integrations and no signed acceptance protocol. Write an annual review of the documentation into the maintenance agreement and record who carries it out.
Checklist
Video
Frequently asked questions
Does the documentation have to be in a single file?
No. What matters is that the package is complete, up to date and signed by both sides. It can be kept in several documents.
What is the audit trail for at acceptance?
It records changes to selected data together with the author and the time, so the partner has evidence of the configuration carried out.
Who keeps the documentation?
The client should have its own copy, and the partner a working copy for maintenance. Record this in the maintenance agreement.
Let's prepare the acceptance document package
We will provide a template for the configuration description and the acceptance protocol. Book a call or a demo.
Let's talk