An automation-error record should let a second person understand what failed, what was decided, and who is responsible without opening every system involved. It is not a dump of screenshots and logs. The useful record connects a specific workflow version and run to the business effect, the chosen response, the evidence retained, and the next decision.
Start with identity and scope
Give the record a unique incident ID. Capture the automation name, platform, environment, workflow ID, version, owner, operational contact, trigger, normal purpose, and affected destination. Add the first observed time, the time zone, the last known-good run, the first known-bad run, and the current state: investigating, contained, fixed pending verification, or closed.
Describe impact in plain language. State which records, customers, messages, inventory items, or internal tasks may be affected. Distinguish confirmed impact from possible exposure. Avoid copying full customer payloads into the incident file; use protected identifiers or links to authorized records. Record whether the automation is still running, paused, or isolated and who approved that state.
Shopify's workflow-run monitoring guidance says each Flow execution creates a run log that can be filtered by workflow, time, errors, actions taken, trigger type, retry status, and run ID. It also notes that completed run data is retained for only 14 days. A durable incident record should therefore capture the relevant run IDs and minimum diagnostic evidence before the platform's short-lived details disappear.
Document settings as a comparison
Do not list only the current configuration. Record the last known-good values and the values at failure for the trigger, filters, conditions, action targets, credential owner, permissions, time zone, retry behavior, concurrency, rate limits, and notification settings. Link to the approved change or deployment that introduced the difference. If the exact prior value is unknown, say unknown instead of reconstructing it from memory.
Use a table with four columns: setting, before, after, and evidence. Redact secrets entirely. A credential should be identified by owner and connection name, not by password, token, or recovery code. For a dynamic field, include a harmless sample and its data type rather than a live personal record.
Record the decision, not just the fix
For each material decision, note the time, decision maker, options considered, chosen action, reason, expected result, risk, rollback trigger, and review time. Examples include pausing the workflow, switching to manual processing, retrying selected runs, restoring a prior version, or accepting a limited delay. A troubleshooting suggestion is not a decision until the named owner approves it.
Shopify's Flow error guidance distinguishes transient errors that may be retried from permanent errors that cannot complete through retry alone. It also explains that error notifications limit noise and may notify only once per workflow version. Documenting that behavior prevents a team from interpreting the absence of another alert as proof that failures stopped.
Keep a controlled retry ledger
Every retry should have the original run ID, retry ID, person, time, reason, source data state, expected effect, and observed effect. Before retrying a write action, verify whether any earlier attempt partially succeeded. Use an idempotency key or another unique business identifier where the system supports it. If the workflow sends messages or changes money, access, orders, or public content, require the appropriate owner before repeating the action.
Separate test runs from production retries. Mark test records clearly and use noncustomer destinations. Attach the exact error text and the failed step, but keep large raw logs in the approved restricted system. The main record should point to them and state their retention period.
Assign closure and follow-up owners
Name one person who can approve restoration and another, if appropriate, who verifies the result. Define closure evidence: the corrected version, controlled test IDs, successful destination checks, absence of duplicates, notification test, monitoring window, and any manually repaired records. List unresolved questions and due dates.
The record is complete when it answers who owns the workflow, which version failed, what changed, how impact was bounded, why each response was chosen, which runs were retried, what proves recovery, and what evidence will remain after platform logs expire.
Sources
- Finding and monitoring workflow runs — Shopify
- Troubleshooting errors in Shopify Flow — Shopify