Workflow Design
Workflow documentation and ownership
Build a discoverable workflow record, dependency map and operating runbook, with clear owners for changes, exceptions and retirement.
Document each workflow so an operator can find its purpose, trace dependencies, establish what happened to an affected item and reach someone authorised to decide the next action.
Give the workflow an operating owner and record who makes business decisions. A diagram without a recovery procedure, or an owner’s name without a working contact route, leaves important questions unanswered.
Keep one discoverable workflow record
Record the business outcome, environment, current version, source and destination systems, operating owner and business decision owner. Point to the controlled workflow configuration and run history. Do not copy credentials into the record.
For a hypothetical paid-order workflow, the record might say that eligible orders should result in fulfilment requests. It should identify who defines eligibility, who supports the automation and who can confirm that a request exists. These may be different teams.
| Document | Question it answers |
|---|---|
| Workflow record | What does this automation do, where does it run and who owns it? |
| Dependency map | Which signals, accounts, services and consumers does it rely on? |
| Operating runbook | How does an engineer inspect, hold, reconcile and resume work? |
| Change record | What changed, who approved it and which dependencies were checked? |
Connect these views without making them duplicates. A configuration export shows steps but may not explain the business rule. A prose description explains intent but may not show the connection currently in use.
Workflow documentation: what each record answers
- Workflow recordWhat does this automation do, where does it run and who owns it?
- Dependency mapWhich signals, accounts, services and consumers does it rely on?
- Operating runbookHow does an engineer inspect, hold, reconcile and resume work?
- Change recordWhat changed, who approved it and which dependencies were checked?
Build a coordinated documentation set
A workflow’s documentation can sit alongside workload wiki pages, architecture diagrams, architectural decision records, standard operating procedures, infrastructure-as-code repositories and API references. These artefacts answer different questions; link them to the workflow record rather than reproducing their contents.
When reviewing the set, identify what already exists, what is missing, which tools hold the material and who will create and maintain it. AWS Well-Architected guidance notes that collecting relevant documentation before a workload review can make the review more efficient.
Make ownership actionable
Name a team responsible for operation and changes. Record who decides business exceptions, who administers source and destination access, and who responds to incidents. Include a maintained contact route and an absence fallback. The original builder can provide context without becoming the permanent owner.
Put decision authority beside the relevant procedure. If an order has an unsupported delivery method, who may correct or reject it? If a source field changes, who assesses the workflow? If a destination write has an unknown outcome, who can inspect its records before another request is sent?
Ownership responsibilities to make actionable
- Team responsible for operation and changes
- Decision owner for business exceptions
- Administrator for source and destination access
- Incident responder
- Maintained contact route
- Absence fallback
Keep ownership definitions consistent
Define what “owner” means for each responsibility: the person or team overseeing changes, supporting troubleshooting, managing administration or accepting risk may not be the same. Record the relevant name, contact information, organisation and team in a central register or resource metadata so operators can identify the right contact.
Prefer a contact route that remains usable when an individual leaves or is unavailable. AWS Well-Architected guidance recommends company-owned email addresses and phone numbers; a group inbox or mapped service queue can provide a maintained route to the responsible team.
Show the system boundaries
Draw the route from source event or schedule through lookups and workflow steps to the destination and later consumers. Use directional arrows and label the connection at each boundary. Record which system is authoritative for each business fact and what evidence confirms the intended result.
An event subscription, service account, API operation and shared queue can change independently of the workflow definition. For each relevant dependency, record its owner, failure impact and change contact. The source-dependency guide covers the upstream register in detail.
Keep diagrams clear and accurate
Use recognised symbols consistently, label components and relationships, and show direction with arrows. If communication is two-way, show separate flows or label the request and response; an unlabelled line or double-headed arrow can leave the dependency unclear.
Maintain diagrams across design, implementation, operations and governance, and retire or update them when they no longer accurately describe the system. A diagram is an abstraction, but oversimplifying a boundary can mislead reviewers and operators.
Link to an operating runbook
Link to a separate operating runbook for detailed procedures; AWS guidance recommends keeping runbooks current as processes evolve.
Maintain the record through change and retirement
Review the documentation when a trigger, data contract, connection, destination operation, owner or recovery route changes. A scheduled review can catch drift.
If a workflow appears unused or loses its owner, investigate its source and consumers before disabling it. Give alerts and exceptions an interim response route while ownership is resolved. The retirement guide covers the steps for retiring a workflow.
Keep controlled material in a central location, such as a version-control system, and update it as the process evolves. AWS guidance treats runbook updates as part of change management.
A change record can connect the approved change to the affected documentation and dependencies.
Review workflow documentation when these change
- Trigger changes
- Data contract changes
- Connection changes
- Destination operation changes
- Owner changes
- Recovery route changes
In this guide
- Documenting a workflow so another engineer can operate itCreate a workflow runbook that lets another engineer find an item, confirm its outcome and recover or escalate it safely.
- Recording source-system dependenciesBuild a source dependency register for a workflow, covering events, lookups, accounts, field contracts, owners and missed-work recovery.
- Assigning an owner to orphaned integrationsStabilise an ownerless integration, identify the teams that depend on it and complete an explicit operational handover.
- Safely retiring a workflow that other systems still useFind a workflow’s remaining consumers, plan a cutover, settle pending and unknown work, and decommission it with an owner.
