node-red-contrib-chronos/nodes/locales/en-US/scheduler.html

Time-based Node-RED scheduling, repeating, queueing, routing, filtering and manipulating nodes

<!--
Copyright (c) 2020 - 2025 Jens-Uwe Rossbach

This code is licensed under the MIT License.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
-->

<script type="text/html" data-help-name="chronos-scheduler">
    <p>
        Schedules the transmission of messages or setting of global/flow variables
        at specific times.
    </p>
    <h3>Details</h3>
    <p>
        This 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.
    </p>
    <p>
        For more information, please refer to the detailed documentation in the
        <a href="https://github.com/jensrossbach/node-red-contrib-chronos/wiki/Scheduler-Node">repository wiki</a>.
    </p>
    <h3>Configuration</h3>
    <dl>
        <dt>Name</dt>
        <dd>The name of the node (optional).</dd>
        <dt>Configuration</dt>
        <dd>
            A reference to the configuration node to be used.
        </dd>
        <dt>Schedule tab</dt>
        <dd>
            List containing the scheduled events. New entries can be added
            using the button below the list. Existing entries can be reordered
            or deleted. For each entry, a schedule time and an output can be
            configured:
            <ul>
                <li>
                    The trigger time can be specified depending on the selection
                    on the left side with the following possibilities:
                    <ul>
                        <li>
                            <i>time of day</i>: A specific time can be entered
                            directly in the form <code>hh:mm[:ss] [am|pm]</code>.
                        </li>
                        <li>
                            <i>sun position</i>: The sun position can be
                            selected from a list of predefined values.
                        </li>
                        <li>
                            <i>moon position</i>: The moon position can be
                            selected from a list of predefined values.
                        </li>
                        <li>
                            <i>custom sun position</i>: One of the user-defined sun position
                            names can be entered.
                        </li>
                        <li>
                            <i>cron table</i>: A cron table can be entered
                            according to <a href="https://github.com/jaclarke/cronosjs#supported-expression-syntax">CronosJS expression syntax</a>.
                        </li>
                        <li>
                            <i>env variable</i>: Trigger configuration will be
                            loaded from the specified environment variable, see
                            section <i>Input</i> below for details.
                        </li>
                        <li>
                            <i>global</i>: Trigger configuration will be loaded
                            from the specified global context variable, see
                            section <i>Input</i> below for details.
                        </li>
                        <li>
                            <i>flow</i>: Trigger configuration will be loaded
                            from the specified flow context variable, see section
                            <i>Input</i> below for details.
                        </li>
                    </ul>
                </li>
                <li>
                    An offset between -300 and +300 can be specified in minutes.
                    The offset will be added to or subtracted from the event
                    time.
                </li>
                <li>
                    If a randomization value between 1 and 300 minutes is
                    specified, the offset will be randomly choosen from a
                    time span of the entered width. The offset value denotes
                    the center of the randomization span in this case.
                </li>
                <li>
                    The output can either be a full message, expressed in JSON
                    form or as JSONata expression, a single message property of
                    different types, a flow variable or a global variable.
                </li>
            </ul>
        </dd>
        <dt>Options tab</dt>
        <dd>
            General options that can be configured and are described below.
        </dd>
        <dt>Start with disabled schedule</dt>
        <dd>
            If selected, the configured schedule will be initially disabled when
            the node starts.
        </dd>
        <dt>Dedicated output ports for schedule events</dt>
        <dd>
            If selected, for each event which produces a message as output, a
            dedicated output port will be created and the output message of the
            event will be sent to the assigned output port. For dynamically
            programmed schedule events via context variables, an output port
            will always be created as it is not known at configuration time, if
            the event will produce an output message or not.
        </dd>
        <dt>
        <dt>Output port for event times</dt>
        <dd>
            If selected, an additional output port will be added. This output
            port emits a message whenever the date and time of any of the
            schedule events is updated. The message contains the timestamp of
            the next schedule event in <code>msg.payload</code> and an array
            with timestamps from all schedule events in <code>msg.events</code>.
        </dd>
        <dt>Delay messages on start</dt>
        <dd>
            If selected, any message that is to be sent directly when the node
            starts is delayed by the specified time (defaults to 0.1 seconds).
        </dd>
    </dl>
    <h3>Input</h3>
    <dt>Enable/disable schedule</dt>
    <dd>
        To either disable or re-enable the schedule or parts of it, a message
        must be sent to the node. Enabling the schedule will also reload any
        programmed schedule events from context variables.
    </dd>
    <dl class="message-properties">
        <dt>payload<span class="property-type">boolean | array</span></dt>
        <dd>Switch(es) for enabling or disabling schedule events</dd>
    </dl>
    <dd>
        If <code>msg.payload</code> is a boolean value, whole schedule is enabled
        if true and disabled otherwise. If <code>msg.payload</code> is an array,
        each element must be a boolean value and corresponds to the event in the
        schedule at the same index. If the value is true, the matching event is
        enabled, otherwise it is disabled.
    </dd>
    <dt>Control scheduler node</dt>
    <dd>
        The scheduler node can be dynamically controlled in various ways using
        an input message.
    </dd>
    <dl class="message-properties">
        <dt>payload<span class="property-type">string | array</span></dt>
        <dd>Controls the node depending on the passed command(s)</dd>
    </dl>
    <dd>
        If <code>msg.payload</code> is a string value, the passed command
        affects the whole schedule. If <code>msg.payload</code> is an array,
        each element must be a string value and corresponds to the event in the
        schedule at the same index affecting only this one.
    </dd>
    <dd>
        The following commands are currently supported:
        <ul>
            <li>
                <code>toggle</code>: Toggles the activation state (i.e., enabled
                events become disabled and vice versa).
            </li>
            <li>
                <code>reload</code>: Forces enabled events to be recalculated
                (also reloads programmed data from environment and context
                variables).
            </li>
            <li>
                <code>trigger</code>: 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.
            </li>
            <li>
                <code>trigger:forced</code>: Same as above, but triggers also
                disabled events, not just enabled ones.
            </li>
            <li>
                <code>trigger:next</code>: Triggers the nearest upcoming event.
                Not supported in array elements, only for <code>msg.payload</code>
                strings.
            </li>
        </ul>
    </dd>
    <dt>Dynamically program schedule</dt>
    <dd>
        The trigger configuration can be dynamically overridden via the input message
        or loaded from an environment or context variable.
    </dd>
    <dl class="message-properties">
        <dt>payload<span class="property-type">array</span></dt>
        <dd>Overrides a single or multiple schedule events</dd>
    </dl>
    <dd>
        The elements of the <code>msg.payload</code> array must be objects
        containing the following properties:
    </dd>
    <dl class="message-properties">
        <dt>type<span class="property-type">string</span></dt>
        <dd>Trigger type; one of "time", "sun", "moon", "custom" or "crontab"</dd>
        <dt>value<span class="property-type">string | number</span></dt>
        <dd>Trigger value; content is depending on trigger type</dd>
        <dt class="optional">offset<span class="property-type">number</span></dt>
        <dd>Offset to the trigger time in minutes (not applicable to type "crontab")</dd>
        <dt class="optional">random<span class="property-type">number</span></dt>
        <dd>Offset randomization span in minutes (not applicable to type "crontab")</dd>
    </dl>
    <dd>
        Additionally it is possible to override the output of the schedule. In
        this case, an extended format must be used for the objects where the
        trigger configuration (see above) is encapsulated by an object property
        called <code>trigger</code> and the following properties are present:
    </dd>
    <dl class="message-properties">
        <dt>output.type<span class="property-type">string</span></dt>
        <dd>Output type; one of "global", "flow", "msg" or "fullMsg"</dd>
        <dt class="optional">output.value<span class="property-type">object</span></dt>
        <dd>Only if output type is "fullMsg"; defines output message content</dd>
        <dt class="optional">output.property.name<span class="property-type">string</span></dt>
        <dd>Only if output type is not "fullMsg"; name of output property/variable</dd>
        <dt class="optional">output.property.type<span class="property-type">string</span></dt>
        <dd>
            Optionally set to "date" and leave <code>output.property.value</code>
            undefined to have same behavior as if selecting <i>timestamp</i> type in UI
        </dd>
        <dt class="optional">output.property.value<span class="property-type">any</span></dt>
        <dd>Only if output type is not "fullMsg"; value of output property/variable</dd>
    </dl>
    <dd>
        Hint: You can also mix boolean, string and objectvalues in the array
        in order to enable/disable, apply control commands to or override
        certain events with a single input message. It is also possible to set
        specific elements in the array to <code>null</code> in order to ignore
        the corresponding events.
    </dd>
    <dd>
        Environment and context variables can be specified as numbers, strings or
        objects. For the latter, the object structure must be the same as for
        message properties, see above. Numbers must be provided as milliseconds
        elapsed since midnight and strings must contain either a time in 12 or 24
        hour format, a sun time, a moon time or a custom sun time.
    </dd>
    <h3>Outputs</h3>
    <p>
        Scheduled messages are sent to the output of this node. The structure and
        content of the message can be statically defined through the configuration
        or dynamically programmed via input message and context variables.
    </p>
</script>