The scheduler node can send messages or set global or flow variables at specific times which are either manually entered or based on sun or moon position. Multiple events can be planned and each can have a different trigger time and produce a different kind of output.

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 scheduler nodes. If omitted, a default name is displayed on the node instance.

Configuration

The configuration node to be used must be selected here.

Schedule

The schedule contains the list of scheduled events that will be triggered at the configured times. New entries can be added to the list using the button at the bottom. Existing entries can be reordered or deleted. Each entry in the list can be configured as described in the following chapters.

Trigger

The first row defines the trigger for the event.

Daily Trigger

The time can be specified as described in section Time Input. On the right to the time input are two numeric fields where an offset and a randomization span can be specified. The offset must be entered in the range of -300 to +300 minutes and will be added to or subtracted from the event time. If a randomization span between 1 and 300 minutes is specified, the offset will be randomized within that time span whereat the specified offset denotes the center of the randomization span.

Cron Table

The scheduler node additionally supports the possibility to declare the trigger using a cron-like schedule specification.

The cron-based trigger type is somewhat different to the other trigger types, see the following comparison:

	Daily Trigger	Cron Table
Trigger Intervals	Once per day	Trigger intervals in the range of years up to the range of seconds
Special Times	Dynamically calculated times based on sun/moon position possible	Only static times supported
Offset	Offset (static or random) can be specified	No offset supported
Filtering	No filtering possible (must be done externally using a time switch or filter node)	Filtering possible (e.g., by days of the week)

The format of the cron table must be according to the CronosJS expression syntax.

Dynamic Trigger

If env variable, global or flow is selected from the dropdown menu, the trigger configuration is loaded from the specified environment or context variable. This allows to dynamically program a schedule and is useful when using the node in a sub flow or if the trigger configuration should be retrieved from a runtime source like e.g., a Node-RED dashboard UI.

The content of such an environment, global or flow variable must follow the basic, extended or structured input format as described in section Time Input. The support for basic and extended formats is limited to time-only values, however. For the structured format, the scheduler node additionally supports the type "crontab", corresponding to the cron table trigger type. For this type, properties offset and random can be omitted.

Trigger times from environment or context variables (except cron table triggers) can have millisecond precision and the node tries to trigger as precisely as possible at that time. However, the exact precision depends on the operating system, the CPU load and some other influencing factors on the Node-RED host and cannot be guaranteed. If multiple events have trigger times within the same second, these events are grouped and triggered together at the full second (i.e., the millisecond part is dismissed).

Examples

The following example is a JSON representation of environment or context variables as they can be loaded by the scheduler node.

Trigger hourly:

{
    "type":  "crontab",
    "value": "0 * * * *"
}

See also examples from section Time Input.

Output

The next two rows define the output of the event. The scheduler node supports sending messages on its output ports as well as setting variables as a result of triggering events.

Different kind of outputs are supported, depending on the selection when clicking on the button on the left side:

The provided possibilities are described in more detail in the following table.

Selection	Description
global.	The output is written to a global variable. The name of the variable has to be entered in the text field on the right to the selection button.
flow.	The output is written to a flow variable. The name of the variable has to be entered in the text field on the right to the selection button.
msg.	The output is sent as a message with a single property. The name of the property has to be entered in the text field on the right to the selection button.
full message	The output is sent as a completely defined custom message.

For global and flow variables as well as message properties, the content is specified on the third row and can be of various types (the types are not described in more detail as they are provided by Node-RED and should be well known):

For full messages, the message structure must be described in the third row either as JSON or as JSONata expression. In both cases, the expressions must evaluate to an object representing the output message.

Hint: You can send multiple messages at the same time by specifying an array of message objects.

JSONata expressions can additionally access some common expression variables and functions as well as the variable $event. The latter is an object and has the following properties:

Property	Type	Description
id	Number	The identifer of the schedule (sequential number starting with 1).
trigger	Object	The trigger configuration of the schedule (see section Dynamic Trigger above for object structure).

Dynamic Output Override

The output can be dynamically overridden if the trigger has been configured to be retrieved from a context variable. To do so, the context variable must be defined using an extended format. In this extended format, the trigger data (see section Dynamic Trigger above) must be encapsulated in an object property called trigger and the following additional properties must be present:

Property	Type	Description
output.type	String	The output type, which can be one of "global", "flow", "msg" or "fullMsg".

If output.type is set to "fullMsg", the following additional property is required:

Property	Type	Description
output.value	Object	Defines the content of the whole output message.

If output.type is set to "global", "flow" or "msg", the following additional properties are required:

Property	Type	Description
output.property.name	String	The name of the output property/variable. In case of context variables, if a variable from a different context store than the default one shall be referenced, the variable name must be specified in the form #:(context_store)::variable_name.
output.property.value	Any	The value of the output property/variable.

The following property can optionally be added and must be set to "date". In this case, the property output.property.value is not required.

Property	Type	Description
output.property.type	String	Output property/variable will contain a timestamp of the message's egress time / the time when the context variable is written (same behavior as if selecting timestamp type in UI).

Examples

The following examples are JSON representations of context variables as they can be loaded by the scheduler node.

Send a full message, i.e. all properties must be specified:

{
    "trigger":
    {
        ...  // see above for examples
    },
    "output":
    {
        "type":  "fullMsg",
        "value":
        {
            "topic":   "all/my/lamps",
            "payload":
            {
                "on": true
            }
        }
    }
}

Send a message with payload set to false:

{
    "trigger":
    {
        ...  // see above for examples
    },
    "output":
    {
        "type":  "msg",
        "property":
        {
            "name":  "payload",
            "value": false
        }
    }
}

Set the flow variable "foo" from default context store to current time:

{
    "trigger":
    {
        ...  // see above for examples
    },
    "output":
    {
        "type":  "flow",
        "property":
        {
            "name": "foo",
            "type": "date"
        }
    }
}

Set the global variable "bar" from disk context store to 42

{
    "trigger":
    {
        ...  // see above for examples
    },
    "output":
    {
        "type":  "global",
        "property":
        {
            "name":  "#:(disk)::(bar)",
            "value": 42
        }
    }
}

Options

If the option Start with disabled schedule is selected, the configured schedule will be disabled initially after the node starts (e.g., after a re-deploy of the flow or after Node-RED starts).

By default, the node has a single output port and all output messages, independent from the originating schedule event, are sent through this port. However, if the option Dedicated output ports for schedule events is selected, the node will potentially spawn multiple output ports instead of a single one.

In this case, for each schedule event producing an output message, a dedicated output port is created and the event's output message is sent out through the corresponding output port. Be aware that the number of output ports does not necessarily match the number of configured schedule events because events that write their output to context variables do not have output ports.

If the option Output port for event times is selected, yet another output port will be added (always the last port on the node). This output port emits a message whenever the scheduled date and time of any of the schedule events is updated. The message has the following format:

Property	Type	Description
msg.payload	Number	The timestamp of the scheduled time for the next/upcoming schedule event.
msg.events	Array	Timestamps of the scheduled times of all configured schedule events. The index in the array matches the position of the event in the configuration.

If option Delay messages on start by X second(s) is selected, any message that is scheduled to be sent directly when the node starts (like for instance event time messages) is delayed by the specified time (defaults to 0.1 seconds).

Input

The scheduler node can be programmatically controlled via specifically formed input messages.

Enable/disable Schedule

It is possible to either disable or re-enable the schedule or parts of it. Enabling the schedule or a schedule event also reloads the configuration from context variables. The msg.payload property must either be a boolean value or an array, see below for details.

Property	Type	Description
msg.payload	Boolean	Enable entire schedule if true and disable otherwise.
msg.payload	Array	Each element of the array must be a boolean value and corresponds to the event in the schedule at the same position. If the value is true, the matching event is enabled, otherwise it is disabled.

Examples

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

{
    "payload": false  // disable entire schedule
}

{
    "payload":
    [
        true,   // enable first event
        false,  // disable second event
        false,  // disable third event
        true    // enable fourth event
    ]
}

Control Scheduler Node

The scheduler node can be dynamically controlled in various ways using an input message. The msg.payload property must either be a string value or an array, see below for details.

Property	Type	Description
msg.payload	String	Control commands affect the whole schedule.
msg.payload	Array	Each element of the array must be a string value and corresponds to the event in the schedule at the same position. Control commands only affect the associated schedule event.

The following commands are currently supported:

Command	Description
toggle	Toggles the activation state (i.e., enabled events become disabled and vice versa).
reload	Forces enabled events to be recalculated (also reloads programmed data from environment and context variables).
trigger	Triggers enabled events, i.e., the output is applied as if the scheduled time has been reached. This does not change the regular schedule time.
trigger:forced	Same as above, but also triggers disabled events, not just enabled ones.
trigger:next	Triggers the nearest upcoming event. Not supported in array elements, only for msg.payload strings.

Examples

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

{
    "payload": "trigger"  // triggers all enabled schedule events
}

{
    "payload":
    [
        "toggle",          // toggle activation state of first event
        "trigger:forced",  // trigger second event (regardless if disabled or not)
        "reload"           // recalculate third event
    ]
}

Override Schedule Events

A single or multiple schedule events can be temporarily overridden via an input message. The overridden configuration will be applied until one of the following situations occurs:

• The overriden schedule event is disabled or reenabled.
• The flow is redeployed or restarted.
• The Node-RED runtime is stopped or restarted.

The msg.payload property must be an array, see below for details.

Property	Type	Description
msg.payload	Array	Each element of the array must be an object and corresponds to the event in the schedule at the same position. The trigger configuration and optionally the output of these events will be overridden.

The format of the array elements is the same as the one for context variables containing dynamic schedule configuration, see above for details.

Examples

The following example is a JSON representation of the complete input message.

{
    "payload":
    [
        // override first schedule event to trigger at 22:30, output is taken from configuration
        {
            "type":   "time",
            "value":  "22:30",
            "offset": 0,
            "random": 0
        },
        // override second schedule event to trigger at sunset minus 15 minutes (randomized across 30 minutes) and override output
        {
            "trigger":
            {
                "type":   "sun",
                "value":  "sunset",
                "offset": -15,
                "random": 30
            },
            "output":
            {
                "type":  "msg",
                "property":
                {
                    "name":  "payload",
                    "value": false
                }
            }
        }
    ]
}

Combined Input

It is possible to mix boolean, string and object values in the msg.payload array in order to enable/disable, apply control commands to and override certain events with a single input message. To ignore specific schedule events, the corresponding elements in the array have to be set to null. If all events to be ignored are at the end of the configuration, the corresponding array elements can simply be omitted.

Examples

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

{
    "payload":
    [
        true,                     // enable first event
        {
            "type":   "sun",
            "value":  "sunrise",
            "offset": 30,
            "random": 20
        },                        // override second event to trigger at sunrise with random offset
        null,                     // ignore third event (do nothing with it)
        "trigger",                // trigger fourth event
        "reload",                 // recalculate fifth event
        false                     // disable last event
    ]
}

{
    "payload":
    [
        null,       // elements for ignored events at the beginning must explicitly be set to null
        true,
        null,       // elements for ignored events in the middle must be set to null as well
        "trigger",
        "trigger"
        // elements for ignored events at the end can simply be omitted
        // null,
        // null,
        // null
    ]
}

Outputs

Scheduled messages, i.e. for events which have set its output type to message property or full message, are sent to the output port(s) of this node. The structure and content of the messages can be defined through the configuration or dynamically programmed via input messages and context variables.