Make integrations understandable
A workflow diagram is useful only if someone can connect it to the real task and the actual systems. Integration records should let your business trace an item, identify its dependencies and understand what can safely be changed. Keep the explanation readable for an operational lead while retaining the technical detail a maintainer needs.
01 Trace the path of an item
Start with the event that begins the process. It might be a form submission, a scheduled check or a change to a record. Describe the source, the conditions that allow processing and the destination. Include branches where an item waits for approval or leaves the automated route.
Microsoft Power Automate is a workflow service known for connecting applications through flows. A record of a flow should explain the trigger and business purpose, not merely reproduce its screen layout. A connector name alone does not establish which environment, list or account the flow uses.
n8n is a workflow automation tool that represents processing through connected nodes. Its visual structure can help trace transformations and decision points. Accompany the configuration with plain-language explanations of those decisions, especially where an expression changes a value or filters out an item.
02 Record meanings as well as connections
HubSpot is known for customer relationship management, while Xero is accounting software. Both illustrate why field meanings matter: a contact record, an invoice and a payment are different business objects. Copying a reference between systems does not make their statuses equivalent.
Record which system holds the authoritative value for each important field. Describe formats, empty values and identifiers used to match records. Avoid matching solely by a display name when names can change or repeat. Where a mapping involves financial or legal interpretation, ask the appropriate specialist to confirm it.
| Record | What it should contain | Why it matters |
|---|---|---|
| Trigger | Event, source and entry conditions | Explains why an item starts |
| Field mapping | Source, destination, format and meaning | Prevents silent reinterpretation |
| Dependency | System, environment and responsible role | Shows where a change may have effects |
| Exception route | Failure signal and next action | Turns an error into manageable work |
| Recovery | Pause, reconciliation and restart procedure | Reduces duplicate or missed processing |
03 Keep configuration separate from secrets
GitHub hosts repositories and supports versioned collaboration. It can hold workflow definitions, supporting scripts and change notes when access is configured appropriately. Version history helps explain what changed, but a repository is not automatically a suitable place for passwords, access tokens or customer exports.
Store secrets through the relevant platform’s credential facilities or an approved secret-management arrangement. Document the credential’s purpose, owner and renewal route without writing its value into the runbook. Review configuration exports before sharing them because they may contain identifiers, sample data or embedded sensitive information.
Maintain a recognisable version of the documentation alongside each accepted configuration. A file named “final” does not tell a maintainer whether it matches the running workflow. Describe how the business identifies the active version and where an earlier recoverable version is kept.
04 Explain dependency failure and recovery
Zapier is known for connecting applications through automated workflows, and Make uses visual scenarios for integration work. Their interfaces differ, but the handover question is the same: what happens when a connected service rejects a request or becomes unavailable?
Record whether failed work is retried, held or abandoned, and where a person sees that state. A retry can create duplicates if the destination accepted an earlier request but its response was lost. Explain how staff reconcile source and destination records before replaying work.
List dependencies beyond application names. Shared folders, mailbox permissions, field names, subscriptions and network arrangements can all affect a workflow. Treat provider documentation as the place to confirm current platform behaviour rather than assuming a screenshot will remain accurate indefinitely.
05 Test the records without their author
Ask a colleague who did not build the workflow to locate its trigger, follow a training item and identify the exception route. If they cannot connect the record to the running system, improve the record before sign-off. This is a documentation check, not a demand that every manager become a developer.
Keep a short contents list and a clear owner for updates. Record the reason for a change as well as the changed setting. The next maintainer needs to know which business rule the setting serves, so they can avoid “fixing” a deliberate control.