Workflow Design
Part of Workflow documentation and ownership
Documenting a workflow so another engineer can operate it
Create a workflow runbook that lets another engineer find an item, confirm its outcome and recover or escalate it safely.
Write the document around the actions a replacement engineer must take: find an affected item, establish its last confirmed result, decide whether work can continue and reach the right owner. A screenshot of workflow steps provides context, but it cannot explain what to do after a lost response or an invalid record.
Start with an operating brief
Put the workflow name, purpose, environment, current version, operational owner and escalation route at the top. State the business result in observable terms. For a hypothetical order workflow: “Each eligible paid order should have one confirmed fulfilment request linked to its source order.” Identify where eligibility is determined and where the destination result can be checked.
List the locations an authorised operator needs: workflow definition, run history, source record, destination record and unresolved-work list. Name the access role for each without recording credentials. State who may hold new work and who may approve a business correction. Make any hand-off between those people explicit.
Write the diagnostic route in order
Follow one affected item:
- Find the source item by a stable reference and check its current eligibility.
- Find the corresponding workflow instance, if one exists, and note its version and last confirmed step.
- Classify the outbound result as confirmed, rejected, accepted for later processing or unknown, according to the destination’s contract.
- Check the destination using the agreed source reference or destination ID.
- Record the item’s status, permitted next action and owner.
Adapt the lookup, status names and permissions to the actual systems. After a create request times out, treat the destination outcome as unknown unless other evidence establishes what happened. Repeating the request solely because the run shows an error can create another effect.
Finding / Instruction the runbook needs
- Source item is ineligible
- How to close it without a destination write
- Input needs correction
- Who may correct it and how processing resumes
- Destination effect is confirmed
- Where to record its ID and close the item
- Destination effect is unknown
- Which lookup or documented safe retry applies; when to escalate
- Shared connection has failed
- Who owns it and how affected work remains visible
Make recovery steps safe to follow
For each permitted action, give its precondition and expected observable result. “Replay the order” is too vague. State which item version remains eligible, what prior destination effect must be checked and which identity the recovery route preserves.
Include a stop condition. If there is no reliable destination lookup or documented safe retry route, assign investigation before another create attempt. For a batch, explain how each failed item remains visible. Keep alert acknowledgement separate from resolving the underlying work.
Keep the document current
Store the runbook where the operating team can find it and assign a maintainer. Update it when a trigger, connection, destination operation, exception route or permission changes. Record the last review date and the workflow version it describes.
A handover check should have an engineer unfamiliar with the workflow trace a safe sample item and explain the next action in a failure case. Record observations only after that check occurs. Missing access, an ambiguous status or an undocumented lookup calls for a runbook correction.
