scheduledHandoff

Source processor and a specialized variant of handoff.

It must be the first processor in a flow, has no external endpoint, and can only receive messages forwarded by a distribute or split processor in an upstream flow.

Where handoff forwards messages immediately, scheduledHandoff delays processing until a configured point in time. Messages whose target time is in the future are forwarded when due; all other messages are passed through immediately.

Like handoff, a scheduledHandoff flow provides its own independent delivery guarantee: every incoming message is persisted at the source before processing begins. This persistence is what gives the flow its own redelivery and dead letter handling, independent of the upstream flow.

scheduledHandoff flows must use exchangePattern = OneWay. The upstream flow hands off and continues immediately after the message is accepted — there is no mechanism for the upstream to wait for a scheduled future processing event.

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.

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.

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.

Sub-builders

Name	Summary
messageLoggingStrategy	Strategy for describing how a processor’s message is logged on the server.
payloadArchivingStrategy	Strategy for archiving payloads.

Name

Summary

messageLoggingStrategy

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

payloadArchivingStrategy

Strategy for archiving payloads.

Details

Usage

Both the distribute and split processors support scheduled handoffs to flows. The handoff flow would be configured in a manner similar to the following:

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

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

    restRequest {
        id = "send-http-request"
        defaultMethod = POST
        address = URL("https://my/url")
    }
}

In the main flow:

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

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?