Asynchronous Execution Replay and Manual Resolution

Overview

The Asynchronous Execution Replay Service provides administrative functions to manage the lifecycle of individual asynchronous API transaction records. It is designed for operators to diagnose and resolve executions that have entered a failed, expired, or otherwise non-terminal state.

This service allows an operator to:

• Preview a replay: Simulate how a stored callback payload would be processed with the current system configuration without changing any data.
• Reprocess a callback: Re-run the callback processing logic using either the stored payload or a newly provided one, and persist the new result. This is useful when response mappings or transformation rules have been updated.
• Manually resolve executions: Force an execution into a completed or failed state when automatic processing is not possible or desired.
• Reopen an execution: Reset a failed or expired execution back to the waiting_callback state, giving it a new expiry window to receive a callback.

The service operates on s2r_async_execution records identified by their unique id. It interacts with the operation's configured response mappings and transformation rules to process SOAP payloads into final JSON results.

How It Works

The service provides several distinct functions for manipulating an asynchronous execution record. The core logic for re-evaluation is centralized in a replay evaluation process.

Replay and Reprocessing Flow

When an operator initiates a replay or reprocess action, the service performs the following steps:

1. Load Execution: It fetches the target s2r_async_execution record from the database using its asyncExecutionId.

2. Evaluate Replay: It uses the SOAP callback payload associated with the execution (either the one stored previously or one provided in the request) to simulate the callback processing.

   flowchart TD
       subgraph Replay Evaluation
           A[Load Mappings and Rules] --> B{Parse SOAP Payload};
           B -- Success --> C[Apply Response Transformations];
           B -- SOAP Fault --> D[Create 'fault' Outcome];
           B -- Parse Error --> E[Create 'parse_error' Outcome];
           C --> F[Compare with Stored Result];
           F --> G[Create 'completed' Outcome];
       end
   
       Start(Start Replay/Reprocess) --> L[Load Async Execution Record];
       L --> P{Has Callback Payload?};
       P -- Yes --> A;
       P -- No --> X1[Throw Exception];
       
       subgraph Final Outcome
           D --> Z;
           E --> Z;
           G --> Z;
       end
   
       Z --> Y{Persist Changes?};
       Y -- Yes --> U[Update Database Record];
       Y -- No (Preview) --> R[Build Response];
       U --> R;
       R --> Stop(End);

   • Mapping and Rules: The service loads the currently active OperationMappingRecord and transformation RuleSet for the operation.
   • SOAP Parsing: It attempts to parse the SOAP payload.
     • If parsing fails (e.g., due to a malformed payload or a mapping mismatch), it generates a parse_error outcome.
     • If the payload is parsed but resolves to a SOAP Fault, it generates a fault outcome.
     • If successful, it proceeds to the next step.
   • Transformation: The extracted payload is processed by the PayloadTransformService to produce the final JSON result. This generates a completed outcome. The new result is compared to the previously stored result to determine if anything has changed.

3. Persistence (Reprocessing only): For reprocess actions, the outcome of the evaluation is persisted. The s2r_async_execution record is updated:

   • On completed, the status is set to completed and the new JSON result is stored in callback_response_payload.
   • On fault, the status is set to failed, the fault details are stored in callback_response_payload, and failure_message is updated.
   • On parse_error, the status is set to failed and failure_message is updated with the parsing error.

4. Response: A detailed JSON object is returned, describing the original state, the replay outcome, the new state (if persisted), and any generated errors or messages.

Manual Resolution

For completeManually and failManually, the service bypasses the replay evaluation. It directly executes a SQL UPDATE statement on the s2r_async_execution record to set the status to completed or failed and records the provided JSON result or failure message.

Reopening an Execution

The reopenAwaitingCallback function resets a non-completed execution. It updates the record's status to waiting_callback, clears all previous callback and result data, and calculates a new expires_at timestamp. The new expiry window is determined by the duration between the original created_at and expires_at timestamps. If that cannot be calculated, it uses the system setting default_retention_days.

Service Methods

The AsyncExecutionReplayService exposes the following methods for administrative clients.

replayPreview

Previews the reprocessing of the stored callback for an async execution without persisting any changes.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.

Returns: A Map<String, Object> containing the replay analysis. The persisted field will be absent. See Response Body Structure for details.

reprocessStoredCallback

Reprocesses the stored callback for an async execution using the current mappings and rules, then persists the result.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.

Returns: A Map<String, Object> containing the replay analysis and final state. The persisted field will be true. See Response Body Structure for details.

replayProvidedCallback

Previews the reprocessing of an async execution using a provided SOAP payload, without persisting any changes.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.
callbackSoapPayload	String	Yes	The full XML SOAP payload to use for the replay.

Returns: A Map<String, Object> containing the replay analysis. The persisted field will be absent. See Response Body Structure for details.

reprocessProvidedCallback

Reprocesses an async execution using a provided SOAP payload and persists the result. The provided payload will be stored in the record.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.
callbackSoapPayload	String	Yes	The full XML SOAP payload to use for the replay.

Returns: A Map<String, Object> containing the replay analysis and final state. The persisted field will be true. See Response Body Structure for details.

completeManually

Forces an async execution into the completed state with a provided JSON result.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.
resultJson	String	Yes	A valid JSON string to store as the callback_response_payload.

Returns: A Map<String, Object> confirming the manual resolution. See Manual Resolution Response Structure for details.

failManually

Forces an async execution into the failed state with a provided reason.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.
failureReason	String	Yes	A text message to store as the failure_message.

Returns: A Map<String, Object> confirming the manual resolution. See Manual Resolution Response Structure for details.

reopenAwaitingCallback

Resets a failed or expired async execution to the waiting_callback state, clearing previous callback data and setting a new expiry date.

Parameter	Type	Required	Description
asyncExecutionId	UUID	Yes	The unique identifier of the async execution.

Returns: A Map<String, Object> confirming the execution has been reopened. See Reopen Response Structure for details.

Response Body Structure

Replay and Reprocess Response

Methods like replayPreview and reprocessStoredCallback return a map with the following structure. The exact fields depend on the replayStatus.

{
  "id": "...",
  "correlationId": "...",
  "environment": "...",
  "serviceKey": "...",
  "operationKey": "...",
  "executionStatus": "completed",
  "mappingVersion": 1,
  "callbackReceivedAt": "...",
  "completedAt": "...",
  "expiresAt": "...",
  "failureMessage": null,
  "storedResult": { "key": "value" },
  "generatedAt": "...",
  "replayStatus": "completed",
  "storedResultChanged": false,
  "persisted": true, // Only if reprocessed
  "storedResultBefore": { "key": "value" }, // Only if reprocessed
  "replayResult": { "key": "value" }, // If replayStatus is 'completed'
  "replayFaultPayload": { "fault": "details" }, // If replayStatus is 'fault'
  "replayError": "Error details...", // If replayStatus is 'parse_error'
  "replayMessage": "Replay result matches the stored callback result."
}

Manual Resolution Response Structure

The completeManually and failManually methods return a map with the following structure.

{
  "id": "...",
  "correlationId": "...",
  "environment": "...",
  "serviceKey": "...",
  "operationKey": "...",
  "executionStatus": "completed",
  "callbackReceivedAt": "...",
  "completedAt": "...",
  "expiresAt": "...",
  "failureMessage": null,
  "storedResult": { "final": "result" },
  "resolutionStatus": "completed",
  "resolutionMessage": "Async execution was completed manually with the provided JSON result.",
  "generatedAt": "..."
}

Reopen Response Structure

The reopenAwaitingCallback method returns a map with the following structure.

{
  "id": "...",
  "correlationId": "...",
  "environment": "...",
  "serviceKey": "...",
  "operationKey": "...",
  "executionStatus": "waiting_callback",
  "statusBefore": "failed",
  "callbackReceivedAt": null,
  "completedAt": null,
  "expiresAt": "...", // New expiry timestamp
  "storedResult": null,
  "resolutionStatus": "reopened",
  "resolutionMessage": "Async execution is waiting for callback again with a refreshed expiry window.",
  "generatedAt": "..."
}

Configuration

The service uses the following system setting.

Name	Type	Default	Description
default_retention_days	Integer	60	When reopening an execution with reopenAwaitingCallback, this value is used to set the new expiry window if the original window cannot be determined from the record's timestamps. The effective value used will be at least 1.

Troubleshooting

Condition / Error	Trigger
IllegalArgumentException: async execution not found	The provided asyncExecutionId does not exist in the database or is not accessible within the caller's tenant scope.
IllegalArgumentException: ... is required	A required parameter (callbackSoapPayload, resultJson, failureReason) was null or blank.
IllegalArgumentException: manual result must be valid JSON	The resultJson string provided to completeManually was not valid JSON.
IllegalStateException: no callback SOAP payload is stored for this execution	A replay or reprocess action was attempted on an execution that has no callback_soap_payload stored. Provide a payload or use a different resolution method.
IllegalStateException: no active response mapping exists for this execution	The operation associated with the execution does not have a currently active response mapping, preventing the service from processing the SOAP payload.
IllegalStateException: completed async executions cannot be reopened	An attempt was made to call reopenAwaitingCallback on an execution that is already in the completed status.
IllegalStateException: async execution is already waiting for callback	An attempt was made to call reopenAwaitingCallback on an execution that is already in the waiting_callback status.
replayStatus: 'parse_error'	The SOAP payload could not be parsed with the current operation mapping. The replayError field in the response contains details.
replayStatus: 'fault'	The SOAP payload was parsed successfully but resolved to a SOAP Fault. The replayFaultPayload field contains the extracted fault details.
executionStatus: 'expired'	This is a derived status. If a record's status is waiting_callback but its expires_at timestamp is in the past, it is considered expired.

See Also

• Operation Response Mapping: For configuring how incoming SOAP callback payloads are parsed.
• Payload Transformation Rules: For configuring how data extracted from callbacks is transformed into the final JSON result.
• System Settings: For general platform configuration.

---

All SOAP-to-REST docs