Fallout Definitions

A fallout definition is the rule that turns a raw failure into a handled fallout. It names the error to match, how to retry it, the retry policy to apply, and whether an operator may edit the payload before retrying. Without a matching definition a failure is still recorded, but nothing retries it automatically.

Before you begin

• The error you want to match exists as an error definition, or you are ready to create one inline.
• A retry configuration exists and is active. Only active configurations are offered in the form at application scope.

Choose the scope

The form differs by where you open it, and the two are not interchangeable.

Scope	Open from	Matches on
Application	The application's Configuration tab > Fallouts > Fallout Definition	A workflow (Service Name), a Step Name, and an Error Definition
Organisation	Fallouts > Fallout Definition in the sidebar	An Error Code only, in any application

Retry From Workflow works at both scopes. When an application-level definition and an organisation-level one both match a failure, the application-level definition takes precedence.

Use application scope when the handling depends on where the failure happened. Use organisation scope for an error that should be handled the same way everywhere. The application-level list also shows organisation-level definitions while the Organization Scope switch beside the search box is on.

Choose the retry method

The first field, Retry Method, decides how Engage re-runs a matching failure and which other fields appear. Choose Retry, Restart, Retry From Step, or Retry From Workflow; an information icon beside each gives a one-line description. The retry method guide explains how to pick and how the names map to the labels in the retry dialog.

Retry Method	Fields shown
Retry, Restart, Retry From Step	Service Name (application scope only), Step Name, Retry From Step, Retry Policy
Retry From Workflow	Retry Workflow in place of the step fields. Retry Policy is hidden, because a workflow retry runs its own flow.

Retry From Step and Retry From Workflow are disabled when the application has no manifest configuration, and the field then defaults to Retry instead of Retry From Step.

Create a definition

1. Select Add Fallout Definition. The Configure Fallout drawer opens.
2. Choose the Retry Method.
3. At application scope with Retry, Restart, or Retry From Step, identify the failing workflow in Service Name, then select the failing step in Step Name and, optionally, the step to resume from in Retry From Step. Both step lists come from the workflow you named, and the workflow's End step is excluded. At organisation scope, Step Name and Retry From Step are offered without a Service Name. With Retry From Workflow, select the Retry Workflow instead, then map the payload as described below.
4. Select the error. At application scope the field is Error Definition; at organisation scope it is Error Code. The list shows each error's code with its description on hover, a globe icon on organisation-scoped entries, and an eye icon that opens the definition read-only. The last entry, Create Error Definition, opens the error drawer without leaving this form.
5. Select the Retry Policy, unless the method is Retry From Workflow. The same list shape applies, and the last entry, Create Retry Policy, opens the retry drawer inline.
6. Leave Retry Channel as it is. It is fixed to HTTP and cannot be changed.
7. Enter a Name and a Description. Both are required.
8. Switch on Allow data modify if an operator should be able to edit the record's payload before a manual retry.
9. Switch on Active. A definition created from this page starts inactive; one created with Define Fallout from a live fallout starts active.
10. Select Create.

The form has no alert field. Alert definitions cannot be attached to a fallout definition in this release; see Alert definitions for how alerting is configured instead.

Map the payload for Retry From Workflow

When Retry From Workflow and a Retry Workflow are chosen, the drawer widens and a schema mapper appears. It maps the failed record's payload, on the left, into the retry workflow's inputs, on the right: its path parameters, query parameters, and request body, as the manifest declares them. Connect fields and add functions as you would in the data mapper; the mapping is saved with the definition and used each time Engage sends a matching fallout to that workflow.

• The left side is read from a real fallout, so it is filled when you open the form with Define Fallout on a live fallout. To map a payload, start from a fallout with Define Fallout; opened from the list, the form has no source fields to show.
• Choosing a different Retry Workflow clears the mapping at once, because the old connections no longer apply.
• If the schemas cannot be loaded the mapper shows Failed to load schemas with the reason.

Define a fallout from a live failure

The quicker route, and the one that fills the form for you. Open a fallout under Global Fallout or the application's Fallouts tab, and select Define Fallout in its details. The drawer opens with the service, step, and previous step pre-filled, and with the failure's error code selected. If no error definition with that code exists yet, Engage creates one from the failure's own name, description, category, and severity before the form appears.

From the application's Fallouts tab this switches you to the Configuration tab, where the drawer lives. From Global Fallout it opens in place, at application scope when the fallout belongs to a provisioned application and at organisation scope when it does not.

Manage definitions

The table shows Name, Error Code, Status, Description, and Actions, with a Service Name column at application scope. The Status switch activates or deactivates a definition in place; Engage confirms with Fallout Definition activated successfully or the deactivated equivalent. Select Edit to reopen the drawer as Edit Fallout Definition and finish with Update; select Delete and confirm to remove it.

How you know it worked

Engage confirms with Fallout Definition created successfully and the definition appears in the table. Failures that match it from now on show that retry policy's attempts on their timeline, and an exhausted one waits in the fallout list with its status set for manual handling. See Retry rules.

When it does not work

Symptom	Cause	What to do
Error code is required or Retry policy is required	A required select is empty	Choose a value, or create one from the last entry in the list
Name is required or Description is required	One of the two text fields is empty	Fill both
The retry policy you expect is missing from the list	It is inactive; application scope lists active configurations only	Switch it on under Retry Config
Step Name offers nothing	Engage has no workflow profile for this application, which is the case for fallouts from applications outside any manifest	Define the fallout at organisation scope instead
Failed to auto-create the detected error definition	Define Fallout could not save an error definition for the failure's code	Create the error under Error Definitions, then define the fallout again
Failed to create fallout definition	The save was rejected; the message names the reason when the service gives one	Correct the named field and select Create again

Next steps

Retry rules explains what the definition does once a matching failure arrives.