Skip to main content

Respond to a failed integration

Outcome. A failed call, message, file record, recurring import or business event is understood, its cause is fixed, and the work is put through again or deliberately ended without posting anything twice; then you make the same failure less likely. Who takes part: Integration operator, Integration administrator, Integration developer, Data management consultant. Stages that use standard pages (Assign users to roles, the standard Business events catalog, the Siren pages) need System administrator or the access named on the role page; the Lattice roles do not open them. How often: each time something fails.

The Integration operator role detects and triages: it sees the monitoring pages, the dead-letter payloads and the File ingestion simulator, but not the file ingestion monitor or the Dead-letter fix and resubmit page. The recovery actions (retry, hold, release, discard, fix and resubmit, mark succeeded, release claim, repair or activate a recurring data job, the business event reconciliation sweep, and the Service test console) need the Integration administrator role, so whoever holds it does stage 4; a caller resends its own refused calls.

1. Detect (Integration operator)​

A failure reaches you through a tile, an alert or a caller. Each kind lands in its own place: a refused call in the service call log, a failed asynchronous operation or file record in the dead-letter queue, a failed import on its recurring data job, a failed publish in the business event log.

Done when: you have the failing item in front of you: a Service call log row, a dead-letter item on Integration operations console, a failed message on Recurring integration details or a Business event log row in Error.

2. Triage (Integration operator)​

Find out what failed and why before anyone changes anything. The error code or error category says who fixes it: the caller (the request), an administrator (setup, role or license), the data owner (the data or the mapping), or nobody (a temporary outage that a retry clears).

Done when: you know the Error code or Error category (for a business event, its Status details and Reconciliation state), whether the request created anything (its claim on Service idempotency log), and who owns the fix.

3. Fix the cause (Integration developer, Integration administrator, Data management consultant)​

Fix the cause where it lives before anything is resubmitted, or the item fails again. The caller fixes its request, the administrator fixes setup, and the data owner fixes the data or the mapping; a corrected file record can be tried in the simulator first.

Done when: the corrected request passes a preview or the File ingestion simulator, the setup it needed is in place, or validateMappings returns Success true for the job's data project.

4. Resubmit or reprocess (Integration administrator, Integration developer)​

Recovery puts the work through again, or ends it on purpose. A replay reuses the original request ID, so a message that in fact posted is not posted twice. A refused direct call is resent by its caller, and a recurring import by its client application: Lattice resubmits neither.

Done when: each item has had its action: the dead-letter item is Retrying, Requeued, Reprocessed or Discarded (or Held, if you chose to hold it), the claim is marked succeeded or released, the recurring data job's Job state is Active, the failed business event is Resolved or was raised again from its source, or the caller or client application has sent the request or file again.

5. Confirm (Integration operator)​

Check the result where the failure first showed, so you know the business document exists and the queue is back to normal.

Done when: the dead-letter item is Reprocessed, the request's claim is Succeeded with the Document ID you expected, a resent business event is Resolved, the tile you started from has dropped, and after Refresh health the recurring data job is no longer Broken. A Failing job stays Failing, and stays on its tile, until its failed messages are older than its failure window (24 hours unless you set another).

6. Prevent a repeat (Integration administrator, Integration developer, Integration operator)​

Ask what would have caught this sooner or stopped it: an alert, a tighter threshold, a mapping check in the release pipeline, a guardrail, or a client that retries safely.

Done when: the change is in place: the alert event is active, the threshold is saved, the mapping check runs in your pipeline, the guardrail is on, or the client change is deployed.

If something goes wrong​