End-to-End Walkthrough
This page follows one failure through both products, from the activity that reports it in Studio to the fallout an operator resolves in Engage. Each stage is short; the linked page holds the detail.
Before you begin
Have these ready before stage 1.
| What | Why | Where |
|---|---|---|
| A Studio application with a tested workflow and a published schema for each event | The manifest and Send to Engage build on them | Prepare an Application for Engage |
| Permission to view and to publish the application's manifest in Studio | Publish is disabled without it | Prepare an Application for Engage |
| The workflow published and deployed in the environment you will watch, Development or Production | Engage shows data per environment | Publishing Workflows |
| An Engage account in an organisation, as an organisation member rather than a tenant user | Tenant users cannot provision or configure | See below |
| Engage permissions for the actions you will take | Controls you lack permission for are disabled with a tooltip | See below |
| Optional: a plan that includes Studio's links to Engage | Studio shows Switch to Engage, Find fallout in Engage, and Open fallout in Engage only then | See stage 7 |
Getting into Engage. A new organisation is created when its first person completes the Create Your Account form (First Name, Last Name, Email, Organization Name, New Password, Confirm Password) from a sign-up link they were sent. That person can then invite others under Organisation > Members; each invitee accepts by email. See Members. Group people into Teams if you prefer to grant permissions once, and invite customers as Tenants only when an application must be shown to someone outside your organisation. Single sign-on is optional.
Permissions by stage. The Admin role has full access. Everyone else needs the permission for each action, granted on their profile or through a team, and a control without it is disabled with a tooltip.
| Stage | Action | Tooltip when missing |
|---|---|---|
| 2 | Provision Application | You don't have access to provision applications. |
| 2 | Configure on an integration | You don't have access to configure this integration. |
| 2 | Syncing an application's manifest | You don't have access to sync this application. |
| 3 | Adding error definitions, retry configurations, and fallout definitions | You don't have access to add error definitions., You don't have access to add retry configurations., You don't have access to configure fallouts. |
| 5 | Retry, Mark as resolved | You don't have access to retry fallouts., You don't have access to mark fallouts as resolved. |
The Fallouts group in the sidebar is available to everyone by default, and Global Fallout is always listed.
1. Report events from Studio
In Studio, a developer sets the Engage context once with a Set Context activity, then places a Send to Engage activity at each milestone of the workflow. Each call reports one event defined in the application's manifest, with data mapped to that event's schema. The developer configures and publishes the manifest, then publishes and deploys the workflow. See Prepare an Application for Engage.
2. Provision and onboard the application in Engage
In Engage, an operator syncs the published manifests, installs the application, and configures its integration: report columns, event mappings, and views. See Onboarding an application, starting with Provision an application. Then run the workflow once and confirm that records arrive with the right columns populated. See Validate the data flow.
3. A failed run becomes a fallout
When a run fails, Engage records a fallout. To decide in advance what happens next, create the three objects in this order: an error definition, a retry configuration, then a fallout definition (the fallout definition form can also create the first two inline). What happens next is decided by fallout definitions, which match the failure to an error definition and a retry configuration. The retry configuration retries automatically; when the retries run out the fallout waits for an operator. See Managing fallouts.
4. Investigate
Start on the Dashboard to see which applications have errors, and select the Fallouts tile, then open Global Fallout for the list across the organisation. The cards above the list count fallouts by status: Total Fallouts, New, Failed, and Resolved. Select a row to open the fallout and read its error, the step that failed, and its trace.
5. Fix and retry
Correct the cause, then retry the fallout. Which retry method fits depends on how far the workflow got before it failed.
6. Confirm it resolved
A fallout that was retried successfully, or marked as resolved by an operator, is counted under Resolved in the status cards. One that was retried and failed again is counted under Failed. Filter Global Fallout by Status to check.
7. Jump back to the Studio trace
The fallout's detail page has an Open in Studio button in its top bar. It opens the run's trace in Studio in a new tab, in the right workspace and environment, so a developer can inspect the failed activity. The button is disabled when the fallout has no trace or workspace. In the other direction, Studio's run history links to the matching fallout. These links need a plan that includes them; without it Studio shows the control disabled with a message such as Switching to Engage isn't included in your plan. See Send to Engage.
Next steps
If the same error keeps returning, define a fallout for it so Engage retries it automatically.