scheduledHandoff

Source processor that delays the processing of messages handed over from other flows.

Processing is postponed until the given datetime. Messages that should be processed in the future are stored and forwarded on the due datetime. All other messages are passed through immediately.

Scheduled handoffs are only meant to be used in OneWay scenarios and immediately ACK all incoming messages. Messages are scheduled with a granularity of seconds.

Configuration properties for the time period (i.e., defaultDelay and maxScheduledDelay) can be set in seconds, minutes, hours, or days using the regex pattern \d+[SMHD]. For example:

10S = 10 seconds
3M = 3 minutes
15H = 15 hours
30D = 30 days

The following options are used to define the message forwarding delay:

scheduledOnDateTimeExpr/dateTimeFormat
delayExpr
defaultDelay

Each of these options (if they are defined) is tried in the above-mentioned order, and the first one that yields a result is used. If none of them are defined, or none of them yield a result, or the yielded result is in the past, the message is passed along immediately.

Messages can be handed off by processors that support distribution of messages (such as distribute and split). The flow ID must contain the suffix -handoff for scheduled handoff flows.

Properties

Name Summary

Name	Summary
`scheduledOnDateTimeExpr`	Optional expression used to select the datetime from the message that defines when the message is forwarded. If set, the expression must be paired with `dateTimeFormat`. This and `dateTimeFormat` have the highest priority when defining the value of the message forwarding delay. If this expression and `dateTimeFormat` are not set, or they don’t yield any result when applied to the message, the values of `delayExpr` and `defaultDelay` are tried next.
`dateTimeFormat`	Format for parsing the datetime from the message, written as a Java DateTimeFormatter string. For example: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. If the datetime format doesn’t include the time zone offset, the time is interpreted as `UTC`. Optional but must be set if `scheduledOnDateTimeExpr` is set. `dateTimeFormat` and `scheduledOnDateTimeExpr` have the highest priority when defining the value of the message forwarding delay. If `scheduledOnDateTimeExpr` and `dateTimeFormat` are not set, or they don’t yield any result when applied to the message, or the yielded result is in the past, the values of `delayExpr` and `defaultDelay` are tried next.
`delayExpr`	Optional expression used to select the delay from the message that defines when the message is forwarded. The value of the expression is expected to be in the time period format of `"10S"`, `"24M"`, etc. `delayExpr` has second priority after `scheduledOnDateTimeExpr` and `dateTimeFormat` when determining the value of the message forwarding delay. If this is not set, or it doesn’t yield a result when applied to the message, `defaultDelay` is tried next.
`defaultDelay`	Optional, hardcoded period of time to wait until the message is forwarded. Specified in the format of the desired time period (e.g., `"10S"`, `"24M"`, etc.). `defaultDelay` is the fallback value when no other options are set, or those options don’t yield any result when applied to the message.
`maxScheduledDelay`	Max period of time the message forwarding can be postponed. Specified in the format of the desired time period (e.g., `"10S"`, `"24M"`, etc.). Defaults to `"1D"` (one day) and cannot exceed the maximum value set by the server. Note that message delays are retrieved from the values of other properties (e.g., `scheduledOnDateTimeExpr` and `dateTimeFormat`), but setting an explicit maximum can ensure that an unreasonable delay isn’t accidentally created. Because there is one source on each server node, this maximum applies per node, not globally.
`maxNumberOfScheduledMessages`	Required, maximum number of messages that can be scheduled for future processing. When this number is reached, all new messages are rejected. Because there is one source on each server node, this maximum applies per node, not globally.
`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`.

scheduledOnDateTimeExpr

Optional expression used to select the datetime from the message that defines when the message is forwarded. If set, the expression must be paired with dateTimeFormat. This and dateTimeFormat have the highest priority when defining the value of the message forwarding delay. If this expression and dateTimeFormat are not set, or they don’t yield any result when applied to the message, the values of delayExpr and defaultDelay are tried next.

dateTimeFormat

Format for parsing the datetime from the message, written as a Java DateTimeFormatter string. For example: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. If the datetime format doesn’t include the time zone offset, the time is interpreted as UTC. Optional but must be set if scheduledOnDateTimeExpr is set.

dateTimeFormat and scheduledOnDateTimeExpr have the highest priority when defining the value of the message forwarding delay. If scheduledOnDateTimeExpr and dateTimeFormat are not set, or they don’t yield any result when applied to the message, or the yielded result is in the past, the values of delayExpr and defaultDelay are tried next.

delayExpr

Optional expression used to select the delay from the message that defines when the message is forwarded. The value of the expression is expected to be in the time period format of "10S", "24M", etc. delayExpr has second priority after scheduledOnDateTimeExpr and dateTimeFormat when determining the value of the message forwarding delay. If this is not set, or it doesn’t yield a result when applied to the message, defaultDelay is tried next.

defaultDelay

Optional, hardcoded period of time to wait until the message is forwarded. Specified in the format of the desired time period (e.g., "10S", "24M", etc.). defaultDelay is the fallback value when no other options are set, or those options don’t yield any result when applied to the message.

maxScheduledDelay

Max period of time the message forwarding can be postponed. Specified in the format of the desired time period (e.g., "10S", "24M", etc.). Defaults to "1D" (one day) and cannot exceed the maximum value set by the server.

Note that message delays are retrieved from the values of other properties (e.g., scheduledOnDateTimeExpr and dateTimeFormat), but setting an explicit maximum can ensure that an unreasonable delay isn’t accidentally created. Because there is one source on each server node, this maximum applies per node, not globally.

maxNumberOfScheduledMessages

Required, maximum number of messages that can be scheduled for future processing. When this number is reached, all new messages are rejected. Because there is one source on each server node, this maximum applies per node, not globally.

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.

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

Usage

Both the distribute and split processors support scheduled handoffs to flows when the flow ID contains the suffix -handoff. This naming pattern is what signals to the main flow that a handoff is taking place. The handoff flow would then be configured in a manner similar to the following:

flowConfig {
    id = "message-scheduling-handoff"
    description = "Message Scheduling Handoff Flow"
    ownerId = "my-company"
    exchangePattern = FlowExchangePattern.OneWay

    scheduledHandoff {
        id = "scheduled-handoff-source"
        maxScheduledDelay = "30S"
        maxNumberOfScheduledMessages = 2
    }

    test {
        id = "log-handoff"
        messageLoggingStrategy {
            logDescription = true
            logFullMessage = true
        }
    }
}

In the main flow, the initiating processor then references the same -handoff flow ID. For example:

distribute {
    id = "distribute-message"
    flowId("message-scheduling-handoff")
}

Caveats

It is important to note that for some flow-server deployments, there is a size restriction on the scheduled messages and the threshold is determined by the flow-server configuration. If the size of a scheduled message exceeds the configured threshold, the scheduled message will be rejected and an error will be reported. Please make sure that the size of scheduled messages is within the configured threshold of the flow-server deployment. This size threshold can be obtained from Utilihive support for the multi-tenant deployment or your operations team for the on-premise deployment.

Was this page helpful?