node-red-contrib-chronos
Version:
Time-based Node-RED scheduling, repeating, queueing, routing, filtering and manipulating nodes
312 lines (306 loc) • 14.4 kB
HTML
<!--
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-switch">
<p>
Routes messages based on specific times.
</p>
<h3>Details</h3>
<p>
This node routes incoming messages to output ports based on the time
of arrival or a timestamp specified via a message property, global
variable or flow variable.
</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-Switch-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>Conditions</dt>
<dd>
The list containing the conditions for routing messages to output
ports. 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>
Operator <i>otherwise</i>: Evaluates to true if all other conditions
do not match.
</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>
<dt>Stop on first match</dt>
<dd>
If selected, evaluation of conditions is stopped on the first match,
i.e. message are never routed to more than one output port.
</dd>
</dl>
<h3>Input</h3>
<p>
Incoming messages are routed to none, one or multiple of the configured
output ports. If the message is delivered to more than one port, it will
be cloned at each but the first port.
</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", "months"
or "otherwise"
</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>
<p>
If <code>operator</code> is "otherwise", <code>operands</code>
is not required.
</p>
<h3>Outputs</h3>
<p>
Each output port is dedicated to a specific condition which is evaluated
against the base time.
</p>
</script>