InnerWeb
Skip to main content

System rollout documentation: what the partner should hand over to the client

An implementation partner that hands the client clear documentation of configuration, roles and acceptance gives it evidence for an internal audit and makes a later change of contractor easier. Below is a set of documents and practices that work well.

5
documents in the recommended package
Source: InnerWeb best practices
99.5%
availability in the maintenance contract
Source: draft partner agreement

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

SLA repair time by request categoryHorizontal bar chart: repair times of 8, 24 and 168 hours for categories A, B and C050100150200hoursCategory ACategory A: 8 hours8Category BCategory B: 24 hours24Category CCategory C: 168 hours168
Source: Sample SLA from the draft partner agreement (B: 1 day, C: 7 days)

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