node-red-contrib-chronos/nodes/locales/en-US/filter.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-filter">
    <p>
        Filters messages based on specific times.
    </p>
   <h3>Details</h3>
    <p>
        This node is similar to the time switch node but instead of routing
        messages to different output ports, it hands over or discards messages
        depending on different conditions.
    </p>
    <p>
        For more information, please refer to the detailed documentation in the
        <a href="https://github.com/jensrossbach/node-red-contrib-chronos/wiki/Time-Filter-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>Base Time</dt>
        <dd>
            The base time is used for comparison with the operands of the
            conditions. This can be one of:
            <ul>
                <li>
                    <i>message ingress</i>: Ingress time of the input message.
                </li>
                <li>
                    <i>global</i>, <i>flow</i>, <i>msg</i>: Time from a context
                    variable or message property. The variables/properties 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>Date and time in region-specific format</li>
                                <li>Date and time in ISO 8601 format</li>
                            </ul>
                        </li>
                    </ul>
                </li>
            </ul>
        </dd>
        <dt>Evaluation</dt>
        <dd>
            Specifies the evaluation method for forwarding messages based on the
            results of the conditions. This can be one of:
            <ul>
                <li>
                    <i>logical OR</i>: The message is forwarded if at least one
                    of the conditions evaluates to true.
                </li>
                <li>
                    <i>logical AND</i>: The message is forwarded only if all
                    conditions evaluate to true.
                </li>
                <li>
                    <i>annotation</i>: The message is always forwarded and
                    the results of the conditions are stored as array of boolean
                    values in the property <code>msg.evaluation</code>.
                </li>
                <li>
                    <i>expression</i>: The message is forwarded if the specified
                    JSONata expression evaluates to true. The results of the
                    conditions can be accessed through the variable <code>$condition</code>
                    which is an array of boolean values.
                </li>
            </ul>
        </dd>
        <dt>Conditions</dt>
        <dd>
            The list containing the conditions for filtering messages. New entries
            can be added using the button below the list. Existing entries can be
            reordered or deleted. Depending on the selected operator or source on
            the left side, the following possibilities are available:
            <ul>
                <li>
                    Operator <i>==</i>: Checks if the base time is the same as the
                    specified time.
                </li>
                <li>
                    Operator <i>!=</i>: Checks if the base time is not the same as the
                    specified time.
                </li>
                <li>
                    Operator <i>before</i>: Checks if the base time is earlier than the
                    specified time.
                </li>
                <li>
                    Operator <i>until</i>: Checks if the base time is earlier than or
                    equal to the specified time.
                </li>
                <li>
                    Operator <i>since</i>: Checks if the base time is equal to or later
                    than the specified time.
                </li>
                <li>
                    Operator <i>after</i>: Checks if the base time is later than the
                    specified time.
                </li>
                <li>
                    Operator <i>between</i>: Checks if the base time is equal to or later
                    than the first and earlier than or equal to the second specified time.
                </li>
                <li>
                    Operator <i>outside</i>: Checks if the base time is earlier than the
                    first or later than the second specified time.
                </li>
                <li>
                    Operator <i>days</i>: Checks if the base time matches special days
                    of a month. This can be the first, second, third, fourth, fifth or
                    last day, day of a week, workday or weekend day. Or it can be an
                    even day or a specific day of a specific month or every month. All
                    operands can be negated by activating the <i>Exclude</i> checkbox.
                </li>
                <li>
                    Operator <i>week days</i>: Checks if the base time matches one of
                    the selected week days.
                </li>
                <li>
                    Operator <i>months</i>: Checks if the base time matches one of the
                    selected months.
                </li>
                <li>
                    Source <i>expression</i>: The condition result is taken from the
                    provided JSONata expression. Additional time calculation functions
                    are supported and the base time can be accessed through variable
                    <code>$baseTime</code>.
                </li>
                <li>
                    Source <i>context</i>: Loads the condition from the specified
                    environment or context variable. See section <i>Input</i> below
                    for a description of the required structure for the variable.
                </li>
            </ul>
            For the time input, 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 12 or 24 hour format. Optionally it is possible to specify
                    a date and a time using regional or ISO 8601 format.
                </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>env</i>, <i>global</i>, <i>flow</i>, <i>msg</i>: The time is
                    retrieved from an environment variable, a context variable or a
                    message property. The variables/properties 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>
                </li>
            </ul>
            The specified times can additionally be shifted by an (optionally
            randomized) offset and set to a certain precision for the comparison.
            These settings are accessible through the expand/collapse arrow on
            the right side.
        </dd>
    </dl>
    <h3>Input</h3>
    <p>
        Incoming messages are either handed over to the output or discarded.
    </p>
    <p>
        Conditions can be dynamically programmed by configuring the corresponding
        condition to be loaded from a context variable (see section <i>Configuration</i>
        above). The appropriate variables must be objects containing the following
        properties:
    </p>
    <dl class="message-properties">
        <dt>operator<span class="property-type">string</span></dt>
        <dd>
            Operator for comparison; one of "equal", "notEqual", "before", "until",
            "since", "after", "between", "outside", "days", "weekdays", or "months"
        </dd>
        <dt class="optional">operands<span class="property-type">object | array</span></dt>
        <dd>Operands for comparison; content is depending on operator</dd>
    </dl>
    <p>
        If <code>operator</code> is:
        <ul>
            <li>"equal", "notEqual", "before", "until", "since" or "after", <code>operands</code> must be an object</li>
            <li>"between" or "outside", <code>operands</code> must be an array containing two objects corresponding to the first and second operand</li>
        </ul>
        The objects must each include the following properties:
    </p>
    <dl class="message-properties">
        <dt>type<span class="property-type">string</span></dt>
        <dd>Operand type; one of "time", "sun", "moon" or "custom"</dd>
        <dt>value<span class="property-type">string</span></dt>
        <dd>Operand value; content is depending on operand type</dd>
        <dt>offset<span class="property-type">number</span></dt>
        <dd>Offset to the operand time in minutes</dd>
        <dt>random<span class="property-type">number</span></dt>
        <dd>Offset randomization span in minutes</dd>
        <dt class="optional">precision<span class="property-type">string</span></dt>
        <dd>
            Comparison precision; one of "millisecond", "second",
            "minute", "hour", "day", "month" or "year"
        </dd>
    </dl>
    <p>
        If <code>operator</code> is "days", <code>operands</code> must be
        an object containing the following properties:
    </p>
    <dl class="message-properties">
        <dt>type<span class="property-type">string</span></dt>
        <dd>
            Operand type; one of "first", "second", "third", "fourth",
            "fifth", "last", "even" or "specific"
        </dd>
        <dt class="optional">day<span class="property-type">string | number</span></dt>
        <dd>
            Depending on the operand type the name of a day or the day
            of the month as number; not applicable for type "even"
        </dd>
        <dt class="optional">month<span class="property-type">string</span></dt>
        <dd>Name of the month; only applicable for type "specific"</dd>
        <dt>exclude<span class="property-type">boolean</span></dt>
        <dd>Negated result</dd>
    </dl>
    <p>
        If <code>operator</code> is "weekdays", <code>operands</code>
        must be an object. It may contain boolean properties with names of
        days of the week. If <code>true</code>, the condition is fullfilled
        for base times on that day or not fulfilled if the property is
        <code>false</code> or not present.
    </p>
    <p>
        If <code>operator</code> is "months", <code>operands</code>
        must be an object. It may contain boolean properties with names of
        months of the year. If <code>true</code>, the condition is fullfilled
        for base times in that month or not fulfilled if the property is
        <code>false</code> or not present.
    </p>
    <h3>Outputs</h3>
    <p>
        If one or multiple conditions match the configured base time according
        to the specified evaluation method, the message is sent out.
    </p>
    <p>
        Only if evaluation method <i>annotation</i> is activated:
    </p>
    <dl class="message-properties">
        <dt>evaluation<span class="property-type">array</span></dt>
        <dd>Contains evaluation results of every condition</dd>
    </dl>
</script>