node-red-contrib-chronos
Version:
Time-based Node-RED scheduling, repeating, queueing, routing, filtering and manipulating nodes
488 lines (482 loc) • 22.8 kB
HTML
<!--
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-switch">
<p>
Routes messages based on specific times or time spans.
</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. Alternatively, time spans based on a specific
time reference can be compared.
</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>Reference</dt>
<dd>
The time reference for the base time (see below). If set to <i>absolute
time</i>, the node is in moment mode and all conditions are compared with
the absolute base time. Otherwise, the node is in duration mode and all
conditions are compared with the time span between reference time and base
time (base duration). The reference time for duration mode can be one of:
<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. 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>env variable</i>, <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>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>
<p>
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.
</p>
<p>
In moment mode, the following possibilities are available depending
on the selected operator or source on the left side:
</p>
<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>
<p>
For the time input, depending on the selection on the left side, the
following possibilities are available:
</p>
<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. 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>env variable</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>
<p>
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.
</p>
<p>
In duration mode, the following possibilities are available depending
on the selected operator or source on the left side:
</p>
<ul>
<li>
Operator <i>=</i>: Checks if the base duration is the same as the
specified duration.
</li>
<li>
Operator <i>≠</i>: Checks if the base duration is not the same as the
specified duration.
</li>
<li>
Operator <i><</i>: Checks if the base duration is less than the
specified duration.
</li>
<li>
Operator <i>≤</i>: Checks if the base duration is less than or
equal to the specified duration.
</li>
<li>
Operator <i>≥</i>: Checks if the base duration is equal to or greater
than the specified duration.
</li>
<li>
Operator <i>></i>: Checks if the base duration is greater than the
specified duration.
</li>
<li>
Operator <i>between</i>: Checks if the base duration is equal to or greater
than the first and less than or equal to the second specified duration.
</li>
<li>
Operator <i>outside</i>: Checks if the base duration is less than the
first or greater than the second specified duration.
</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. The reference time can be accessd through
variable <code>$refTime</code> and the base time can be accessed through
variable <code>$baseTime</code>. Additionally, the time span between
reference time and base time can be accessed through variable
<code>$baseDuration</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>
<p>
For the duration input, depending on the selection on the left side, the
following possibilities are available:
</p>
<ul>
<li>
<i>number</i>: The duration can be entered as a number. The unit
has to be chosen from the dropdown box on the right side.
</li>
<li>
<i>string</i>: The duration can be entered as ASP.NET style time
span or in ISO 8601 format.
</li>
<li>
<i>env variable</i>, <i>global</i>, <i>flow</i>, <i>msg</i>: The duration is
retrieved from an environment variable, a context variable or a
message property. The variables/properties can have the following
format:
<ul>
<li>
Number (duration in milliseconds)
</li>
<li>
String
<ul>
<li>Duration as ASP.NET style time span</li>
<li>Duration in ISO 8601 format</li>
</ul>
</li>
</ul>
</li>
</ul>
</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).
</p>
<p>
In moment mode, 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>
<p>
In duration mode, 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", "less", "lessOrEqual",
"greater", "greaterOrEqual", "between", or "outside"
</dd>
<dt class="optional">operands<span class="property-type">number | string | array</span></dt>
<dd>Operands for comparison; content is depending on operator</dd>
</dl>
<p>
If <code>operator</code> is:
<ul>
<li>"equal", "notEqual", "less", "lessOrEqual", "greater" or "greaterOrEqual", <code>operands</code> must be a number or a string</li>
<li>"between" or "outside", <code>operands</code> must be an array containing two elements being either a number or a string</li>
</ul>
If the operand is a number, it represents the duration in milliseconds. If
it is a string, it can be specified either as ASP.NET style time span or in
ISO 8601 format.
</p>
<h3>Outputs</h3>
<p>
Each output port is dedicated to a specific condition which is evaluated
against the base time or base duration.
</p>
</script>