Fixing a Fallout
The fallout page puts the fix first. It tells you what failed and why, lets you correct the data a retry sends, and keeps every earlier run in a timeline so you can see whether your fix worked. This page walks one fallout from opening it to closing it.
Before you begin
- The fallout is in a manual state. Retrying, and editing the data, are available only once Engage has stopped retrying automatically; see Retry rules.
- Your role can remediate fallouts. Without that permission the actions are disabled and say You don't have access to retry fallouts.
- To edit the data, the matching fallout definition has Allow data modify on.
Open a fallout
Select a row in Global Fallout or in an application's Fallouts tab. You can also open one from a link that carries its fallout ID. The header shows where it failed, its status, and its fallout ID with a copy button.
The header actions are:
| Action | What it does |
|---|---|
| Fix / Metrics | Switches between the fix view and the full workflow trace |
| Open in Studio | Opens the trace in Studio in a new tab. Disabled, with the tooltip Studio can't show this fallout (no trace or workspace), when there is nothing to open. |
| Mark as resolved | Closes the fallout without re-running it |
| Define Fallout / View Fallout | Opens the fallout definition form pre-filled from this failure. It reads View Fallout when a definition already matched, and opens that definition read-only. See Fallout definitions. |
Below the header, the Runs strip lists the original run and each retry as a chip with its result. Select a chip to look at that run in Metrics. Latest in Studio opens the newest run in Studio.
Read what happened
The Failure summary card shows the recorded error message, with a button to copy it.
When Engage can tell which value the failing request used, it names the step and field,
for example that the request used a step's meterId, and says that if the value is
wrong you should change it and retry.
Select Details on the right for the facts behind the failure:
| Row | Meaning |
|---|---|
| Engine status | The lifecycle status, in the same words as the list |
| Runs | How many runs there have been and whether they failed the same way |
| Error type | The error definition the failure matched |
| Fallout definition | The matched definition, or None matched |
| Retry policy | How the definition retries, and how many automatic retries are used |
| Next automatic retry | When Engage will try again, if it will |
| First failed | When the fallout was first recorded |
The Steps card lists the workflow's steps. The failed step reads Failed here · no output saved. Select a step to show its saved output in the retry data; select the All steps entry, Every step together, as a retry sends it, to show them all. See every step's timing in Metrics switches to the trace.
Edit the input
The Retry data panel holds the data a retry sends. Choose how to see it in Show data as:
- Form shows each field as an input suited to its type. Fields the failing request used are marked Used in the failing request and listed first under Likely the field to change; the rest are under All fields. Filter long lists with Filter fields by name or value.
- JSON shows the raw output of the selected step. Once you change something, switch between Edit and Changes to see a diff of what you changed.
Each changed field shows its original value and an undo link. Revert step or Revert all undoes your edits. If a step's JSON is invalid the panel says Invalid JSON. Fix it before retrying. and the retry is held until you correct it.
The panel is read-only when the fallout is not editable, and says why:
| Message | Meaning |
|---|---|
| Editable once the fallout needs manual action. | Engage is still retrying automatically |
| This fallout is closed. Its retry data is kept for reference. | It is already resolved |
| Data changes are turned off for this fallout. | The definition has Allow data modify off |
| You don't have access to retry fallouts. | Your role lacks the permission |
If you leave with unsent edits, a Discard your changes? dialog asks you to confirm. It reads N changed field(s) haven't been sent in a retry. Select Discard changes to leave or Keep editing to stay.
Read the Metrics and the status timeline
Select Metrics to see the full workflow trace for the run on screen. A bar above it names the run and offers Compare with original run. The retry controls move to a bar along the bottom, with Edit the input to return to the form on the step you were looking at. When a run other than the newest is on screen, the bar reminds you that a retry sends the fallout's current data, not that run's.
The Status timeline on the right lists everything that happened to the fallout, newest first, grouped by run:
- Each run is a row on one connected line: Original run, then Retry 1, Retry 2, and so on, with the result Succeeded, Failed, or In progress. A retry that was sent but never reported back reads No result. Select a run to show it in Metrics.
- Back-to-back retries that failed the same way fold into one row such as Retries 2–4, marked same error. Open it to see each one.
- Resolving the fallout closes it rather than a run, so those events sit above the runs.
- An event reading Retry sent means the request was accepted, not that it worked. The run's result follows when it reports back.
- Select View event data on an event to read its data, step through events with Previous and Next, and use Copy content to copy it.
- Routine status bookkeeping is hidden: each retry also writes a lifecycle status change and a status change, which would list every retry three times. The newest row carries the fallout's end state, such as Manually Recovered, in the same words as the list.
Select Collapse timeline to give the page more width; it starts collapsed on narrow screens. When a fallout has no timeline, the right-hand side shows Service, Step, Source Channel, and the error's Name, Code, and Message instead.
Retry
The Retry options section sits under the retry data, and along the bottom in Metrics. It preselects the method the fallout definition uses, marked (recommended).
-
Choose how to retry:
Option What it does Re-run the failed step Runs the failed step again with the data above, keeping what the steps before it did Run the whole workflow again Runs every step from the start, including any that send data to other systems. Your edits are not sent. Run again from a step… Runs the step you pick in From step and every step after it, keeping the output of the steps before it Send to a retry workflow… Sends the data to a published retry workflow you pick in Retry workflow, and asks for any path or query parameters it needs -
Below the select, a line states what will be sent: Sends the data as recorded., or Sends N changed fields.
-
Select the button. Its label follows your choice, for example Re-run Validate, Run workflow again, Run again from Validate, or Send to the workflow's name, with with changes added when you edited data. If Engage judges that retrying unchanged is unlikely to help, the button ends anyway.
Engage reports Retry sent successfully. If the request is rejected you see Retry failed. See Choosing a retry method for which to pick.
While a retry is out, the button is disabled and reads the reason, such as Retry 3 is in progress. Its result will show here. When it reports back, Engage says Retry N succeeded., Retry N failed with the same error., or Retry N failed.
In Metrics, select a step and use the Run from step instead link on the bar to switch to Run again from a step… starting at it.
Confirm the result
A fallout is closed in one of these ways. The header and failure summary name the outcome, who closed it, when, and why.
| Outcome | Meaning | How it happens |
|---|---|---|
| Recovered | A retry succeeded | Automatically or by your retry. The status reads Recovered or Manually Recovered. |
| Resolved | Someone closed it without a successful retry | Select Mark as resolved, enter a Reason, and select Mark as Resolved. Engage reports Marked as resolved, and the reason is saved to the timeline. |
| Superseded | A newer fallout replaced this one | Set by Engage |
Mark as resolved is disabled once a fallout is resolved, with the tooltip This fallout is already resolved. A resolved fallout cannot be retried.
When it does not work
| Symptom | Cause | What to do |
|---|---|---|
| Retry is only available once this fallout reaches Manual status. | Engage is still retrying automatically | Wait for the Exhausted tag, or for the retries to finish |
| Fix the invalid JSON above before retrying. | A step's JSON does not parse | Correct it in the JSON view |
| Choose the step to run again from. or Choose a retry workflow. | The choice needs a step or workflow | Pick one |
| No published retry workflows found for this fallout | The application's manifest lists none, or none is published | See Choosing a retry method |
| The definition's retry workflow isn't available, so a plain re-run is selected. | The definition names a retry workflow that is no longer published | Pick another option, or fix the definition |
| Retry never reported back | A retry was sent but no result returned | Mark the fallout resolved if it is no longer needed |
| Fallout not found, or you don't have access to it. | The link's ID is wrong or belongs elsewhere | Check the ID and your organisation |
Next steps
If the same error keeps coming back, stop fixing it by hand: define a fallout for it so Engage retries it automatically.