node-red-contrib-chronos/nodes/locales/en-US/delay.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-delay">
    <p>
        Delays each message passing through the node for a configurable amount
        of time or until a specific point in time is reached.
    </p>
    <h3>Details</h3>
    <p>
        This node queues incoming messages either for a configurable (and
        optionally random) amount of time or until a specific point in time is
        reached. The point in time can be either manually entered or based on
        sun or moon position.
    </p>
    <p>
        When the time span has passed or the configured moment in time has
        been reached, all messages in the queue are forwarded to the output
        of the node.
    <p>
        For more information, please refer to the detailed documentation in the
        <a href="https://github.com/jensrossbach/node-red-contrib-chronos/wiki/Delay-Until-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>Delay Type</dt>
        <dd>
            The type of delay which can be specified as follows:
            <ul>
                <li>
                    <i>Fixed Duration</i>: The delay is configured by a fixed
                    time span.
                </li>
                <li>
                    <i>Random Duration</i>: The delay is configured by a time
                    span range from which a random duration is choosen.
                </li>
                <li>
                    <i>Point in Time</i>: The delay is configured by a point
                    in time at which it ends.
                </li>
                <li>
                    <i>Custom</i>: The delay is specified by a user-defined
                    JSONata expression or taken from a context variable.
                </li>
                <li>
                    <i>Unlimited</i>: The delay is unlimited and the queue
                    must be flushed explicitly via an appropriate input
                    message.
                </li>
            </ul>
        </dd>
        <dt>Duration</dt>
        <dd>
            Either the fixed duration expressed in milliseconds, seconds,
            minutes, hours or days, after which queued messages should be
            forwarded, or a duration range in milliseconds, seconds,
            minutes, hours or days. In the latter case, the duration will
            be a random value within that range. If <i>Random value always
            in milliseconds granularity</i> 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.
        </dd>
        <dt>When</dt>
        <dd>
            The target time when queued messages should be forwarded. Depending
            on the selection on the left side, the following possibilities are
            available:
            <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>
            </ul>
        </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 target 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>Delay</dt>
        <dd>
            If <i>expression</i> is selected, specifies a JSONata expression
            that must result in a time value for the delay. The time value
            can be a number either containing the duration in milliseconds or
            the amount of milliseconds elapsed since the UNIX epoch representing
            the point in time when the delay ends. The latter can also be
            expressed as a datetime string. When selecting <i>env variable</i>,
            <i>global</i>, <i>flow</i> or <i>msg</i>, the delay 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>fixedDuration</code>, <code>randomDuration</code>
            and <code>when</code>).
        </dd>
        <dt>Limit queue</dt>
        <dd>
            If selected, the message queue can be limited to a maximum number
            of messages that will be queued.
        </dd>
        <dt>When message arrives on input and queue is full</dt>
        <dd>
            Specifies the behavior when a message arrives at the input port
            and the queue limit is already reached.
            <ul>
                <li>
                    <i>drop incoming message</i>: The incoming message will
                    be dropped.
                </li>
                <li>
                    <i>drop oldest message</i>: The oldest message in the
                    queue will be dropped and the incoming message will be
                    enqueued.
                </li>
                <li>
                    <i>flush oldest message</i>: The oldest message in the
                    queue will be sent out and the incoming message will be
                    enqueued.
                </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 still
            be 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 delayed
            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 queueing
        behavior of the node if the following properties are existing.
    </p>
    <dl class="message-properties">
        <dt class="optional">drop<span class="property-type">any</span></dt>
        <dd>
            If present, all message in the queue are dropped without being
            sent out.
        </dd>
        <dt class="optional">flush<span class="property-type">any</span></dt>
        <dd>
            If present, all message in the queue are immediately being sent
            out.
        </dd>
        <dt class="optional">enqueue<span class="property-type">any</span></dt>
        <dd>
            Can be combined with either of the above properties. If present,
            this message will be enqueued after dropping/flushing.
        </dd>
        <dt class="optional">fixedDuration<span class="property-type">object</span></dt>
        <dd>
            Overrides the fixed duration after which queued messages should be
            forwarded, see below for details.
        </dd>
        <dt class="optional">randomDuration<span class="property-type">object</span></dt>
        <dd>
            Overrides the random duration after which queued messages should be
            forwarded, see below for details.
        </dd>
        <dt class="optional">when<span class="property-type">object</span></dt>
        <dd>
            Overrides the target time when queued messages should be forwarded,
            see below for details.
        </dd>
    </dl>
    <p>
        If a property called <code>fixedDuration</code> is present in the input
        message, the fixed duration until forwarding all currently and later
        enqueued messages 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 delay</dd>
        <dt>unit<span class="property-type">string</span></dt>
        <dd>The unit for the duration, one of "milliseconds", "seconds", "minutes", "hours" or "days"</dd>
    </dl>
    <p>
        If a property called <code>randomDuration</code> is present in the input
        message, the random duration until forwarding all currently and later
        enqueued messages is overridden. The property must have the following
        content:
    </p>
    <dl class="message-properties">
        <dt>value1<span class="property-type">number</span></dt>
        <dd>The lower bound of the duration range</dd>
        <dt>value2<span class="property-type">number</span></dt>
        <dd>The upper bound of the duration range</dd>
        <dt>unit<span class="property-type">string</span></dt>
        <dd>The unit for the duration range, one of "milliseconds", "seconds", "minutes", "hours" or "days"</dd>
        <dt class="optional">randomizerMillis<span class="property-type">boolean</span></dt>
        <dd>Random value always in milliseconds granularity</dd>
    </dl>
    <p>
        If a property called <code>when</code> is present in the input message,
        the target time for forwarding all currently and later enqueued messages
        is overridden. The property must have the following content:
    </p>
    <dl class="message-properties">
        <dt>type<span class="property-type">string</span></dt>
        <dd>Target time type; one of "time", "sun", "moon" or "custom"</dd>
        <dt>value<span class="property-type">string | number</span></dt>
        <dd>Target time value; content is depending on target time type</dd>
        <dt class="optional">offset<span class="property-type">number</span></dt>
        <dd>Offset to the target time in minutes</dd>
        <dt class="optional">random<span class="property-type">number</span></dt>
        <dd>Offset randomization span in minutes</dd>
    </dl>
    <h3>Outputs</h3>
    <p>
        Depending on the delay type, delayed messages are sent to the output when
        the duration has passed or the target time has been reached and addionally
        when a message with the <code>flush</code> property is received. If a
        message with the <code>drop</code> property is received, the messages are
        discarded.
    </p>
</script>