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

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

<!--
Copyright (c) 2020 - 2026 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-repeat">
    <p>
        Repeats each message passing through the node based on a configurable
        interval.
    </p>
    <h3>Details</h3>
    <p>
        This node forwards an incoming message upon reception and then periodically
        sends this messages according to the configured interval or cron-like
        schedule. The repetition ends when a new message is received and optionally
        at a specific time.
    </p>
    <p>
        For more information, please refer to the detailed documentation in the
        <a href="https://github.com/jensrossbach/node-red-contrib-chronos/wiki/Repeat-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>Mode</dt>
        <dd>
            The repetition mode which can be either simple (see "Interval" below),
            advanced (see "Cron Table" below) or custom (see "Expression" below).
        </dd>
        <dt>Interval</dt>
        <dd>
            In simple mode, this specifies the interval for message sending repetition
            which can be expressed in seconds, minutes or hours.
        </dd>
        <dt>Cron Table</dt>
        <dd>
            In advanced mode, this specifies the cron-based schedule for message
            repetition which must be entered according to
            <a href="https://github.com/jaclarke/cronosjs#supported-expression-syntax">CronosJS expression syntax</a>.
        </dd>
        <dt>Repetition</dt>
        <dd>
            In custom mode, when <i>expression</i> is selected, this specifies a
            JSONata expression that is evaluated on each iteration and must result
            in a time value for the next iteration. The time value can either be a
            number containing the amount of milliseconds until the next trigger or
            the amount of milliseconds elapsed since the UNIX epoch representing
            the absolute time of the next trigger. Or it is a valid datetime string
            representing the absolute time of the next trigger. When selecting
            <i>env variable</i>, <i>global</i>, <i>flow</i> or <i>msg</i>, the
            repetition is taken from the specified environment/context variable or
            message property. See section <i>Input</i> below for a description of
            the format (properties <code>interval</code> and <code>crontab</code>).
        </dd>
        <dt>Until</dt>
        <dd>
            The condition when periodic message sending should stop. A subsequently
            received message always stops the repetition of the previous message.
            Additonally a time-based or custom ending condition can be configured
            for message sending repetition. Depending on the selection, the following
            possibilities are available:
            <ul>
                <li>
                    <i>next message</i>: Repetition is only stopped when receiving
                    another message.
                </li>
                <li>
                    <i>time of day</i>: A specific ending 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. A preview of the time is shown when hovering
                    over the button.
                </li>
                <li>
                    <i>moon position</i>: The moon position can be selected from a list
                    of predefined values. A preview of the time is shown when hovering
                    over the button.
                </li>
                <li>
                    <i>custom sun position</i>: One of the user-defined sun position names can be
                    entered.
                </li>
                <li>
                    <i>expression</i>: A JSONata expression can be entered which should
                    evaluate to either <code>false</code> (ending condition not reached)
                    or <code>true</code> (ending condition reached). The time of the
                    next trigger can be accessed via expression variable <code>$next</code>.
                </li>
                <li>
                    <i>env variable</i>: Ending condition will be loaded from the specified
                    environment variable, see section <i>Input</i> below for details.
                </li>
                <li>
                    <i>global</i>: Ending condition will be loaded from the specified global
                    context variable, see section <i>Input</i> below for details.
                </li>
                <li>
                    <i>flow</i>: Ending condition will be loaded from the specified flow
                    context variable, see section <i>Input</i> below for details.
                </li>
                <li>
                    <i>msg</i>: Ending condition will be loaded from the specified message
                    property, see section <i>Input</i> below for details.
                </li>
            </ul>
        </dd>
        <dt>Date</dt>
        <dd>
            A date can be provided in the form <code>YYYY-MM-DD</code> for the
            ending time. If omitted, the date of the message ingress is used.
        </dd>
        <dt>Offset</dt>
        <dd>
            An offset between -300 and +300 can be specified in minutes. The offset
            will be added to or subtracted from the repetition ending time.
        </dd>
        <dt>Randomization</dt>
        <dd>
            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.
        </dd>
        <dt>When message arrives on input</dt>
        <dd>
            Specifies the behavior upon message ingress.
            <ul>
                <li>
                    <i>do nothing</i>: The message is not forwarded on ingress,
                    next sending of the message happens after the first interval
                    has passed (provided that the end condition is not reached).
                </li>
                <li>
                    <i>forward message</i>: The message is immediately forwarded
                    provided that the end time is not exceeded or no end time has
                    been set.
                </li>
                <li>
                    <i>forced forward message</i>: The message is immediately
                    forwarded regardless if the end time has been exceeded or
                    not.
                </li>
            </ul>
        </dd>
        <dt>Preserve control properties in messages</dt>
        <dd>
            If selected, control properties as described below in section
            <i>Input</i> are not deleted from input messages and hence are still
            present in the messages when they are sent to the output port.
        </dd>
        <dt>Ignore control properties in messages</dt>
        <dd>
            If selected, control properties as described below in section
            <i>Input</i> are ignored. This is useful if messages to be repeated
            contain properties with the same names as the control properties
            and hence prevents their misinterpretation.
        </dd>
    </dl>
    <h3>Input</h3>
    <p>
        The input message is forwarded as is but can also control the
        behavior of the node for that message if the following properties are
        existing.
    </p>
    <dl class="message-properties">
        <dt class="optional">stop<span class="property-type">any</span></dt>
        <dd>
            If present, message sending repetition is immediately stopped.
            The message containing this property is discarded.
        </dd>
        <dt class="optional">interval<span class="property-type">object</span></dt>
        <dd>
            Overrides the interval for message sending repetition, see below
            for details.
        </dd>
        <dt class="optional">crontab<span class="property-type">string</span></dt>
        <dd>
            Overrides the cron table for message sending repetition.
        </dd>
        <dt class="optional">until<span class="property-type">object</span></dt>
        <dd>
            Overrides the condition when message sending repetition should end,
            see below for details.
        </dd>
        <dt class="optional">ingress<span class="property-type">string</span></dt>
        <dd>
            Overrides the behavior upon message ingress. Possible values are
            "noop", "forward" and "forward:forced".
        </dd>
    </dl>
    <p>
        If a property called <code>interval</code> is present in the input
        message, the interval for repetition is overridden. The property must
        have the following content:
    </p>
    <dl class="message-properties">
        <dt>value<span class="property-type">number</span></dt>
        <dd>The duration of the interval</dd>
        <dt>unit<span class="property-type">string</span></dt>
        <dd>The unit for the interval duration, one of "seconds", "minutes" or "hours"</dd>
    </dl>
    <p>
        If a property called <code>until</code> is present in the input message,
        the condition when message sending repetition should end is overridden.
        The property may be <code>null</code>, in this case the repetition ends
        only upon reception of the next message. Otherwise the property must
        have the following content:
    </p>
    <dl class="message-properties">
        <dt>type<span class="property-type">string</span></dt>
        <dd>Ending time type; one of "time", "sun", "moon" or "custom"</dd>
        <dt>value<span class="property-type">string | number</span></dt>
        <dd>Ending time value; content is depending on ending time type</dd>
        <dt class="optional">date<span class="property-type">string</span></dt>
        <dd>Ending date in the form <code>YYYY-MM-DD</code></dd>
        <dt class="optional">offset<span class="property-type">number</span></dt>
        <dd>Offset to the ending time in minutes</dd>
        <dt class="optional">random<span class="property-type">number</span></dt>
        <dd>Offset randomization span in minutes</dd>
    </dl>
    <p>
        Environment and context variables for the repetition ending time can be
        specified as numbers, strings or objects. For the latter, the object
        structure must be the same as for message property <code>until</code>,
        see above. Numbers and strings can have the following format:
        <ul>
            <li>
                Number (timestamp)
                <ul>
                    <li>
                        Number of milliseconds elapsed since the UNIX
                        epoch (universal time)
                    </li>
                    <li>
                        Number of milliseconds elapsed since midnight
                        (local time) if value is smaller than 86.400.000
                    </li>
                </ul>
            </li>
            <li>
                String
                <ul>
                    <li>Time in 12 or 24 hour format</li>
                    <li>Sun time</li>
                    <li>Moon time</li>
                    <li>Custom sun time</li>
                    <li>Date and time in region-specific format</li>
                    <li>Date and time in ISO 8601 format</li>
                    <li>Date and sun time</li>
                    <li>Date and moon time</li>
                    <li>Date and custom sun time</li>
                </ul>
            </li>
        </ul>
    </p>
    <h3>Outputs</h3>
    <p>
        Messages are sent to the output upon reception and periodically until
        the next message or a message with the property <code>stop</code> has
        been received. If configured, message sending repetition also ends when
        the ending time has been reached.
    </p>
</script>