suspendMessage

Processor that suspends processing of a message and waits for a correlated resume message before continuing.

Suspended messages will be persisted reliably until the resume message arrives, or one of the thresholds defined by maxNoOfMessagesToKeep and maxAgeInSecondsForMessagesToKeep is passed.

When a resume message matching the correlation ID of a suspended message is received, the following happens:

  • The suspended message, including any payload selected with suspendedPayloadExpr, is combined with the payload of the resume message and forwarded to the next flow processor.

  • An ACK is sent back to the sender of the resume message.

When one of the persistence thresholds is passed on an unresumed suspended message, the message is evicted and a non-transient error returned upstream.

When a resume message that cannot be correlated to a suspended message arrives, a NACK is sent back to the sender of the resume message.

Properties

Name Summary

messageCorrelationIdExpr

The expression used to select the correlation ID from the suspended message.

suspendedPayloadExpr

Optional expression used to select what to store as the payload of the suspended message. If not set, the payload will not be stored, but suspension will still be performed.

Take care to store as little data as possible, since the payload will be persisted and possibly cached in memory.

maxNoOfMessagesToKeep

The maximum number of suspended messages to store for the processor before evicting the oldest one.

maxAgeInSecondsForMessagesToKeep

The maximum number of seconds to store a suspended message before it is evicted.

name

Optional, descriptive name for the processor.

id

Required identifier of the processor, unique across all processors within the flow. Must be between 3 and 30 characters long; contain only lower and uppercase alphabetical characters (a-z and A-Z), numbers, dashes ("-"), and underscores ("_"); and start with an alphabetical character. In other words, it adheres to the regex pattern [a-zA-Z][a-zA-Z0-9_-]{2,29}.

exchangeProperties

Optional set of custom properties in a simple jdk-format, that are added to the message exchange properties before processing the incoming payload. Any existing properties with the same name will be replaced by properties defined here.

retainPayloadOnFailure

Whether the incoming payload is available for error processing on failure. Defaults to false.

Sub-builders

Name Summary

messageLoggingStrategy

Strategy for describing how a processor’s message is logged on the server.

payloadArchivingStrategy

Strategy for archiving payloads.

inboundTransformationStrategy

Strategy that customizes the conversion of an incoming payload by a processor (e.g., string to object). Should be used when the processor’s default conversion logic cannot be used.

Details

Implementation

The typical use case for suspend and resume processors is when you expose a synchronous endpoint but depend on an asynchronous callback to be able to provide a response. This is normally solved by adding a suspendMessage processor as the first processor on a headless flow. For example:

flowConfig {
    id = "suspension-flow"
    description = "Suspension Flow"
    ownerId = OWNER_ID
    exchangePattern = Headless

    suspendMessage {
        id = "suspend-message"
        maxNoOfMessagesToKeep = 10
        maxAgeInSecondsForMessagesToKeep = 60
        messageCorrelationIdExpr = "123"
        suspendedPayloadExpr = "envelope.payload"
    }

    ...
}

You then create two separate flows that send messages to the suspension flow using distribute processors: one for the original synchronous request and one for the callback. The resume/callback flow must contain a resumeMessage processor that will send a resumption message to the suspension flow, which will then produce the response for the original request.

It is also possible to implement suspend and resume using only one flow. In this case, you must configure the messageSelectionExpr property on the resumeMessage processor to determine which messages to process and which to forward and suspend unchanged. For example:

resumeMessage {
    id = "resume-message"
    messageSelectionExpr = "envelope.payload.myProperty == 'valueToProcessOn'"
    messageCorrelationIdExpr = "123"
}

Payloads

When a request is made to the resume flow, an ack response is sent back to the caller. The incoming resume payload is used as the response, which will be formatted in the following manner:

{
  "correlationId": "123",
  "resumedPayload": {
    "myProperty": "someValue"
  }
}

Unless your resume flow is OneWay, you will typically need to transform the final response (i.e., by using a map processor).

The suspendMessage processor, on the other hand, produces a payload that includes both the resume payload and the original request’s payload (if any was specified on the suspendedPayloadExpr property). An example output would look like the following:

{
  "suspendedPayload": {
    "myProperty": "someValue"
  },
  "resumedPayload": {
    "myOtherProperty": "someOtherValue"
  }
}