Skip to content
Webb Technologies

Illustrative sample, not a client project

This handover package is for an invented project, written to show what the document you’d receive contains.

Illustrative sample · handover package

Sample handover package: what your team receives.

Everything your team needs to run, change and recover the system without us, for the same invented dashboard as the sample scope.

Email to a colleague

Jump to the document ↓

Illustrative sample, not a client project

The client, plant, systems and names in this document are invented. It shows the structure and level of detail of the document you'd receive; it is not a record of work for a client.

Handover package · index

Line 3 production and downtime dashboard

Client
Example Manufacturing Co. (fictional)
Prepared by
Webb Technologies
Document
Handover package index and sign-off
Status
Illustrative sample, not a client project

1.How to use this index

This index lists everything handed over at the end of the project described in the sample scope. Each item says where it lives and who holds it after handover. The Client's team works through the checklist in section 11 and signs section 12 once every item is confirmed.

Nothing here appears for the first time at handover. The code, infrastructure and documentation have been in the Client's repositories and accounts from the start. Handover confirms that, moves the last credentials, and proves the Client's team can run the system without us.

2.Repositories

Repositories in the Client's GitHub organization and what each contains

Repository
line3-collector
Contains:
The DMZ collector: PI Web API and OPC UA readers, local buffering, outbound push to the API, install script and service configuration.
Notes:
No write code paths. Tests run against recorded historian responses.
Repository
line3-dashboard
Contains:
The API, database migrations and the web dashboard.
Notes:
API and screen tests run on every change.
Repository
line3-infrastructure
Contains:
The AWS CDK app for the test and production environments.
Notes:
Every AWS resource the system uses is defined here.

All three keep their full history. Each has a README covering local setup, how to run the tests and how to make a first change.

3.Infrastructure as code

  • Stacks. Network and security, data (database and backups), API, dashboard hosting (S3 and CloudFront), monitoring (CloudWatch alarms and dashboard), and the pipeline's deployment role.
  • Environments. test and prod, deployed from the same code, with per-environment settings in one reviewed file.
  • Rebuild from scratch. An empty AWS account can be brought to a working environment by running the pipeline. The steps are in the deploy runbook.
  • Nothing outside code. A final check confirms that no resource in either environment was created by hand.
  • DMZ host. The collector's host is provided by the Client. Its install script and service configuration live in line3-collector, not in the CDK app.

4.CI/CD pipeline

  1. On every pull request: lint, type-check, unit tests and a dependency scan.
  2. On merge to main: build, deploy to test, then smoke tests against test.
  3. To production: a named Client approver approves the step in GitHub Actions, and the same build is deployed to prod.
  4. The collector is packaged by the same pipeline and installed on the DMZ host by the Client's team, following the deploy runbook. The pipeline has no network path into the DMZ.

The pipeline authenticates to AWS with OIDC and a deployment role in the Client's account. No AWS keys are stored in GitHub.

5.Architecture

The architecture document is one diagram and a page of text, kept in line3-infrastructure. The diagram is reproduced below.

Data flow, read-only, one directionBuilt in this projectExisting, Client-ownedOT network · Line 3unchangedIndustrial DMZClient AWS accountAWS CDK · test and prodBusiness networkOT boundaryHTTPSread-only login · VPNClient network onlyPLCs and HMIsAllen-Bradley PLCs · FactoryTalk View SEKepwareOPC UA serverPlant PIhistorianLine 3 collectorread-onlyOPC UA · PI Web APIPI serverreplicaexistingAPI anddatabaseDashboardS3 and CloudFrontCloudWatch alarmsAWS Secrets ManagerSQL Servervw_ShiftCalendarvw_IdealRatesSupervisors'browsersIdentity providerClient's SSOsign-inNothing in AWS or on the business networkopens a connection into the OT network.
Architecture of the Line 3 dashboard (illustrative). Arrows show the direction data moves; every connection is read-only. Solid outlines are built in this project; dashed outlines are the Client's existing systems.

In words, the diagram shows four zones:

Four zones, from the plant outward: the OT network with Line 3's PLCs, HMIs, the Kepware OPC UA server and the plant historian; the industrial DMZ with the PI replica and the read-only collector; the Client's AWS account with the API, database, dashboard hosting, alarms and secrets; and the business network with the SQL Server views and the supervisors who sign in. Data moves only away from the plant.

Data moves in one direction, away from the plant. The collector reads the Kepware OPC UA server and the DMZ's PI server replica, read-only, and pushes outbound over HTTPS. The API reads the two SQL Server views through a read-only login, over the Client's site-to-site VPN between the business network and its AWS account. Nothing in AWS or on the business network opens a connection into the OT network. The only connection into the OT network is the collector's read-only OPC UA session to the Kepware server, opened from the DMZ on a single firewall rule the Client's network team controls.

6.Runbooks

Deploy

  1. Merge the reviewed pull request to main. The pipeline deploys to test and runs smoke tests.
  2. Check the test dashboard's Line status screen against the HMI.
  3. Approve the production step in GitHub Actions.
  4. Confirm the release version in the dashboard footer and that the data-stale alarm is clear.

Roll back

  1. Re-run the production deployment of the last good release from the GitHub Actions history.
  2. If the release included a database migration, run its documented down step first, or restore the most recent backup.
  3. Record the rollback and its reason in the change log.

Rotate credentials

  1. The owning team issues the new credential at its source: the PI Web API account, the OPC UA user or the SQL Server login.
  2. Update the value in AWS Secrets Manager, or in the DMZ host's protected store for the collector's credentials.
  3. Restart the collector service and confirm the data-stale alarm stays clear.
  4. Disable the old credential at its source.

Add a tag or a line

  1. The controls team confirms the tag exists in PI (and, for live values, in the Kepware tag group) and grants the read-only accounts access to it.
  2. Add the tag to the data dictionary and to the line configuration file in line3-collector.
  3. For a new line, add its entry to the line configuration in line3-dashboard; the screens are generated per line.
  4. Deploy through the pipeline and check the new values against the historian, as in acceptance criterion AC2.

Respond to an alert

Each alarm in section 9 links to a short procedure: what it means, what to check first, and who to call on the Client's side.

7.Data dictionary

Fields the dashboard uses, where each comes from and how often it refreshes

Field
line_state
Source:
OPC UA: Line3.State
Type and unit:
Running, idle, faulted, planned stop
Refresh:
On change
Notes:
Mapping from PLC state codes agreed with controls.
Field
good_count
Source:
PI: L3_GoodCount
Type and unit:
Integer, units
Refresh:
30 s
Notes:
Shift totals read from PI, not summed by the dashboard.
Field
reject_count
Source:
PI: L3_RejectCount
Type and unit:
Integer, units
Refresh:
30 s
Notes:
As above.
Field
run_rate
Source:
Calculated
Type and unit:
Units per minute
Refresh:
30 s
Notes:
From good_count over the last five minutes.
Field
ideal_rate
Source:
SQL Server view vw_IdealRates
Type and unit:
Units per minute
Refresh:
Hourly
Notes:
Per product.
Field
shift
Source:
SQL Server view vw_ShiftCalendar
Type and unit:
Name, start, end
Refresh:
Hourly
Notes:
Plant local time.
Field
downtime_event
Source:
Derived from line_state history in PI
Type and unit:
Start, end, duration
Refresh:
On change
Notes:
Stops of 2 minutes or longer (AC3).

The full dictionary in line3-collector also lists each tag's PI point name, engineering units and the controls engineer who confirmed it.

8.Access and credential handover

Every account and credential, who holds it after handover and what happens to it at handover

Item
GitHub organization and repositories
Held by after handover:
Client IT
Action at handover:
Our member access removed.
Item
AWS account, test and prod
Held by after handover:
Client IT
Action at handover:
Our named users removed; the pipeline role remains.
Item
Pipeline deployment role (OIDC)
Held by after handover:
Client IT
Action at handover:
Trust limited to the Client's repositories; reviewed together.
Item
PI Web API read-only account
Held by after handover:
Controls engineering
Action at handover:
Password rotated.
Item
OPC UA read-only user and collector certificate
Held by after handover:
Controls engineering
Action at handover:
Password rotated; certificate re-issued by the Client.
Item
SQL Server read-only login
Held by after handover:
Plant IT
Action at handover:
Password rotated.
Item
SSO app registration and groups
Held by after handover:
Client IT
Action at handover:
Ownership confirmed; our test accounts deleted.
Item
DMZ collector host
Held by after handover:
Plant IT
Action at handover:
Our remote access removed.
Item
Domain name and TLS certificate
Held by after handover:
Client IT
Action at handover:
Confirmed in the Client's account, with automatic renewal.
Item
Alert recipients
Held by after handover:
Client on-call
Action at handover:
Our addresses removed from notifications.

Secret values are handed over in the secrets manager, never in this document, email or chat.

9.Monitoring and alerts

Alarms, what triggers each one and who receives it

Alarm
Data stale
Triggers when:
No new values from the collector for 10 minutes.
Goes to:
Plant IT on-call
Alarm
Collector errors
Triggers when:
Repeated read failures from PI or the OPC UA server.
Goes to:
Plant IT and controls engineering
Alarm
API errors
Triggers when:
Server errors above the threshold agreed in phase 1.
Goes to:
Client IT
Alarm
Sign-in failures
Triggers when:
Failed sign-ins above the threshold agreed in phase 1.
Goes to:
Client IT security
Alarm
Backup failed
Triggers when:
The nightly database backup did not complete.
Goes to:
Client IT

A CloudWatch dashboard shows data freshness, API errors and response times for both environments. Each alarm links to its runbook.

10.Known limitations

  • Downtime reasons are not captured. The log shows when and for how long the line stopped, not why; operator reason entry was out of scope.
  • Live values depend on the Kepware OPC UA server. If it is unavailable, the Line status screen marks its data as stale; shift totals still come from PI.
  • Current-shift counts can trail the HMI by up to 30 seconds. Completed-shift totals come straight from the historian.
  • Changes to the shift calendar in SQL Server appear on the dashboard within an hour.
  • Only Line 3 is configured. Other lines are added with the “Add a tag or a line” runbook.
  • The dashboard is read-only and reachable only from the Client's network. There is no mobile app or offline mode.

11.Knowledge-transfer sessions

  • Architecture walkthrough with IT, controls and security, recorded.
  • Code tour of each repository with the developers who will maintain it.
  • Supervised deployment: a Client developer ships a small change to production through the pipeline.
  • Rollback and recovery: the Client's team rolls back a release and restores the database from backup in test.
  • Test incident: the data-stale alarm is triggered on purpose and the on-call person follows the runbook.
  • Credential rotation: the Client's team rotates one credential using the runbook.
  • Questions log reviewed; every open item answered or documented.

12.Sign-off

Handover is complete when every item in this index is confirmed and both parties sign. Support after handover, if wanted, is agreed separately and in writing.

Client product owner

Name
Signature
Date

Client IT lead

Name
Signature
Date

For Webb Technologies

Name
Signature
Date

Use it as a checklist

What to confirm before you sign a handover.

The test of a handover is whether your team could keep the system running if the people who built it were unreachable.

  1. Your team has deployed and rolled back.

    Not watched a demo: done it themselves, using the runbooks, while the builder is still available to help.

  2. Every credential has a new owner.

    Each account is listed with who holds it now, secrets are rotated, and the builder's access is visibly gone.

  3. Alerts reach your people.

    Every alarm has a named recipient on your side and a runbook that says what to do first.

  4. Limitations are written down.

    What the system doesn't do, and where it depends on other systems, is on paper rather than in someone's head.

  5. Everything is already in your accounts.

    Repositories, cloud resources and the pipeline should have been yours from the start. Handover confirms it.

Keep reading

The companion sample.

Related:Plant-floor demo (simulated data)Brief for your IT, security and controls teamGuide: what a proper handover includes

Want a system your team can run without us?

A 30-minute call to start. Handover is written into the scope, not bolted on at the end.

Request a scoping callinfo@webb-technologies.com