The delay node is similar to the Node-RED delay node but additionally to delaying messages for a certain (optionally random) amount of time, it can also queue incoming messages until a specific point in time is reached or until a specific control message is sent to the node. The delay can be specified in various ways including sun or moon position based times. Upon reaching the target time or receiving a special control message, all messages in the queue are forwarded to the output port of the node.

Configuration

On the configuration page, various settings of the node can be configured.

General

Name

The name is optional and can be used to better distinguish different delay until nodes. If omitted, the target time (or sun/moon position) and the offset (if not equal to 0) are displayed on the node instance. If offset randomization is configured, the offset is prefixed by "~".

Configuration

The configuration node to be used must be selected here.

Delay

The delay during which incoming messages are queued can be configured as fixed duration, random duration, point in time when the delay ends or by a custom expression. It can also be set to unlimited for a complete control over the queuing period from outside.

Fixed Duration

When the delay type is set to Fixed Duration, the delay is configured via a fixed time span which is a single value expressed in milliseconds, seconds, minutes, hours or days, after which queued messages should be forwarded.

Random Duration

When the delay type is set to Random Duration, the delay is configured via a time span range from which a random duration is choosen. A lower bound and an upper bound value expressed in milliseconds, seconds, minutes, hours or days must be entered. If both values are equal, the behavior is the same as if a fixed duration delay type would have been selected. For convenience, it's not mandatory that the upper bound value is greater than the lower bound value, a valid range is always formed between both bounds. The time span after which queued messages should be forwarded will be a random value within that range.

If Random value always in milliseconds granularity is activated, the random value will always have milliseconds granularity, independent from the choosen time unit. Otherwise the granularity of the random value will follow the time unit. For instance if the range is 4 - 7 seconds, with the option being deactivated, the possible random durations would be 4s, 5s, 6s or 7s. If the option is activated on the other hand, there would be thousands of more possible values like 5.236s, 6.868s etc.

Point in Time

When the delay type is set to Point in Time, the delay is configured via an absolute point in time at which it ends. The time when the message buffer shall be flushed and all queued messages shall be forwarded to the output port can be specified as described in section Time Input.

An offset can be entered in the range of -300 to +300 minutes and will be added to or subtracted from the target time. If a randomization span between 1 and 300 minutes is specified in the second numeric field, the offset will be randomized within that time span whereat the specified offset denotes the center of the randomization span.

Custom

When the delay type is set to Custom, the delay can be specified via a user-defined JSONata expression that must result in a time value expressed as either a string or a number. Any property of the first queued input message (i.e., the input message that starts the delay) or an input message containing an override property (see section Input below) can be accessed in the expressions. For an explanation why only the first message or a message with an override property can be inspected, see section Input further down. Additionally there are some common expression variables provided.

The following table describes how the expression result is interpreted.

Type	Range	Description
String	Point in time must be at least one millisecond from now and must not be more than one week in the future.	String representation of the absolute date and time at which queued messages should be forwarded. The string must follow the basic format as described in section Time Input. For time-only values the date of the current day is applied.
Number	1 ≤ n ≤ 604800000	The relative time span in milliseconds after which queued messages should be forwarded.
Number	now + 1 ≤ n ≤ now + 604800000	The absolute date and time in milliseconds elapsed since the UNIX epoch at which queued messages should be forwarded.

Any value outside of the ranges given above leads to an error.

Alternatively, the delay can be taken from an environment or context variable or an arbitrary property of the input message. The format of the variables/properties is the same as for the override properties fixedDuration, randomDuration and when from the input message, see section Input for more information. The node detects the delay type (Fixed Duration, Random Duration or Point in Time) automatically based on the variable/property format.

Unlimited

When the delay type is set to Unlimited, queued messages will never be sent out automatically after some delay period but instead, the message queue must be flushed explicitly via an appropriate input message (see section Input below).

Options

If option Limit queue to X messages is selected, an upper limit for the message queue can be specified and the queue will never exceed this limit. The behavior for an incoming message when the queue is full can be selected under When message arrives on input and queue is full:

Option	Description
drop incoming message	The incoming message will immediately be discarded and not enqueued.
drop oldest message	The oldest message in the queue will be dropped and the incoming message will be enqueued.
flush oldest message	The oldest message in the queue will be sent out and the incoming message will be enqueued.

If the option Preserve control properties in messages is selected, control properties as described in section Input below are not deleted from enqueued input messages and hence still be present in the messages when they are sent to the output port.

If the option Ignore control properties in messages is selected, control properties as described in section Input below are ignored. This is useful if messages to be delayed contain properties with the same names as the control properties and hence prevents their misinterpretation.

Input

Incoming input messages are passed through delayed but can also be used to control the queueing behavior of the node. For this purpose, the following so called control properties can be added to a message:

Property	Type	Description
drop	Any	Drops all queued messages if present.
flush	Any	Sends out all queued messages immediately if present.
enqueue	Any	Enqueues control message.

The control properties drop and flush are mutually exclusive but can both be combined with the property enqueue if needed. The latter only has a meaning when being paired with one of the other two. By default, a message containing either drop or flush is treated a control message and thereby is discarded and not enqueued. But sometimes it is required that a normal message which shall pass through the node, must control the queueing at the same time. This can be achieved by adding the property enqueue, which changes the default behavior and the control message is treated like any other message, i.e. it will be enqueued and forwarded after the delay. As all previous messages in the queue are either dropped or sent out, the control message will then be the first new message in the queue.

Additionally some configuration of the node can be overridden by specifying one of the following properties in the input message:

Property	Type	Description
fixedDuration	Object	Overrides the fixed duration after which queued messages should be forwarded.
randomDuration	Object	Overrides the random duration after which queued messages should be forwarded.
when	Object	Overrides the target time at which queued messages should be forwarded.

If a property called fixedDuration is present in the input message, the delay type is set to fixed duration and the duration until forwarding all currently and later enqueued messages is overridden.

The property must have the following content:

Property	Type	Mandatory	Description
value	Number	yes	The duration of the delay.
unit	String	yes	The unit for the duration, one of "milliseconds", "seconds", "minutes", "hours" or "days".

If a property called randomDuration is present in the input message, the delay type is set to random duration and the duration range for calculating a random duration until forwarding all currently and later enqueued messages is overridden.

The property must have the following content:

Property	Type	Mandatory	Description
value1	Number	yes	The lower bound of the duration range.
value2	Number	yes	The upper bound of the duration range.
unit	String	yes	The unit for the duration range, one of "milliseconds", "seconds", "minutes", "hours" or "days".
randomizerMillis	Boolean	no	If true, the random value will always be in milliseconds granularity.

If a property called when is present in the input message, the delay type is set to point in time and the target time for forwarding all currently and later enqueued messages is overridden. The format of the property when must follow the structured input format as described in section Time Input.

If multiple of these overriding properties are present in the input message, property randomDuration takes precedence over property fixedDuration and property when takes precedence over property randomDuration.

As there is only one queue per node existing, all currently and later enqueued messages are affected by overrides via fixedDuration, randomDuration or when. Unlike drop and flush, these properties do not prevent a message from being enqueued and hence there is no need to add an extra enqueue property.

Calculation of some dynamic values (random duration, target time from sun/moon position and offset randomization) as well as evaluation of JSONata expressions only happens upon reception of the first incoming message when the queue is empty or when a message with an appropriate override is received. All subsequently enqueued messages (without overrides) do not alter the queue configuration anymore.

Examples

The following examples are JSON representations of the complete input message.

Drops all queued messages including this one:

{
    "drop": true
}

Sends out all queued messages immediately and enqueues this one:

{
    "topic":   "my/holy/message",
    "payload": 42,
    "flush":   true,
    "enqueue": true
}

Delays message for 2 seconds:

{
    "payload": true,
    "fixedDuration":
    {
        "value": 2,
        "unit":  "seconds"
    }
}

Changes target time to sunset minus 15 minutes (randomized across 30 minutes):

{
    "payload": "My overriding message",
    "when":
    {
        "type":   "sun",
        "value":  "sunset",
        "offset": -15,
        "random": 30
    }
}

Outputs

The output port forwards the queued messages - depending on the delay type - either when the duration has passed or when the target time has been reached and additionally if a message with the property flush was received.