Time Change Node
The time change node is similar to the Node-RED change node, but all set and change operations are based on date and time values. The node sets message properties, flow variables or global variables to specific timestamps or timespans or manipulates and converts timestamps or timespans from these input fields. Multiple actions can be configured per node which will be executed in the specified order. It is also possible to chain different actions for the same property or variable.
On the configuration page, various settings of the node can be configured.
The name is optional and can be used to better distinguish different time filter nodes. If omitted, a default name is displayed on the node instance.
The configuration node to be used must be selected here.
The time mode, which can be either Moment for moments in time or Duration for periods of time. Depending on the selected mode, the change rules expect either a timestamp or a timespan as input and interpret the provided value accordingly.
The change rules are executed one after another. New entries can be added to the list using the button at the bottom. Existing entries can be reordered or deleted. Each entry in the list can be configured as follows:
The action defines the type of operation to be executed. The provided possibilities are described in more detail in the sections below.
The target defines the input value that will be set or modified. This can be either a message property, a flow variable or a global variable. Depending on the time mode, the value is interpreted and generated differently.
Note: If the target value is a global or flow context variable, intermediate results of rules for the same target will be stored in the variable during rule processing before the final rule applies its result.
In moment mode, the value is interpreted as timestamp value in either basic or extended format, see section Time Input for more information. For time-only values the date of the current day is applied. The resulting value produced by a Set or Change action (see below) will be a numerical UTC timestamp represented as number of milliseconds elapsed since the UNIX epoch. Please be aware that numerical UTC timestamps do not carry any time zone information. If you need a time value for local time in a specific time zone, you have to convert it with the Convert action into a string-based format.
In duration mode, the value is interpreted as timespan value in duration format, see section Time Input for more information. The resulting value produced by a Set or Change action (see below) will be a numerical timespan represented as number of milliseconds.
Depending on the selected time mode, sets/overwrites the target value either with a date and time value representing a moment in time or with a timespan.
In moment mode, the time value can be specified in various ways.
The provided possibilities are described in more detail in the following table:
| Selection | Description |
|---|---|
| current time | Sets the target value to the current time. |
| date & time | Sets the target value to a specific date and time. The date has to be entered in the form YYYY-MM-DD and the time has to be specified as described in section Time Input. |
| expression | Sets the target value to the result of the provided JSONata expression. All properties from the input message can be accessed and the selected target value is available through the variable $target. Additionally there are some common expression variables and function extensions provided, see JSONata Expressions for details. The expression must result in a time value (i.e., either a number or a string, see below for supported formats). |
In duration mode, the timespan is described by specifying a start time (first row) and an end time (second row).
The times have to be specified as described in section Time Input. Additionally to what is described there, time change node supports to enter a time at a specific date if time of day is selected. This can be specified either in region-specific or in ISO 8601 format (see section Time Input for examples). For time-only values the date of the current day is applied. When selecting current time, the current time is used as start or end time.
When selecting env variable, global, flow or msg, the time is retrieved from the specified environment variable, context variable or property of the input message. The time can be provided in the basic or extended format as described in section Time Input. For time-only values the date of the current day is applied.
If the second time is before the first time and both times have no explicitly provided date (and hence, the date of the current day is applied), depending on whether one of the times is set to current time, the first time is shifted one day into the past or the second time is shifted one day into the future, forming a range of a maximum of 24 hours from the first to the second time. If the first and the second time have different dates and the second time is before the first time, the two times are flipped to form a valid range.
Modifies the selected target according to the configured manipulation and conversion rules. The different possibilities for changing the target are described in below sections.
Modifies a part of the target timestamp. The part to be changed can be selected in the dropdown box. The value to be set has to be entered as number or can be retrieved from an environment/context variable or message property. Days of a week range from 1 to 7 and the interpretation of the first day of the week is depending on the current locale of the Node-RED host (e.g., in Germany, 1 means Monday, in the US, 1 means Sunday).
Adds time to or subtracts time from the target timestamp (in moment mode) or target timespan (in duration mode). The amount of time has to entered as number or can be retrieved from an environment/context variable or message property. The unit of time to be added/subtracted can be selected in the dropdown box.
Sets the target timestamp to the start or end of a unit of time. The unit of time can be selected in the dropdown box. The start and end of a week is depending on the current locale of the Node-RED host (e.g., in Germany, start is Monday and end is Sunday, in US, start Sunday and end is Saturday).
Depending on the time mode, the convert action converts the target value into various other formats.
Converts the target timestamp to a string representation in various ways, optionally applying a different time zone or UTC offset.
In the first row, the format of the output string can be chosen:
| Selection | Description |
|---|---|
| predefined format | The timestamp is represented as string in various formats, see below for format description. |
| custom format | The timestamp is represented as string in a custom format, see below for possible formatting options. |
When selecting predefined format, one of the following formats can be selected from the dropdown list:
| Selection | Description |
|---|---|
| regional | Creates a string containing the local date and the time in a region-specific format. |
| regional (date only) | Creates a string containing the local date in a region-specific format. |
| regional (time only) | Creates a string containing the local time in a region-specific format. |
| relative time | Creates a string representing the local time relative to the current time, being less precise the farer away it is. |
| calendar | Creates a string containing the absolute local time (if not farer away than one week) and the local date relative to today (or absolute if farer away than one week). |
| ISO‑8601 | Creates a string containing the local date and the time in ISO-8601 format. |
| ISO‑8601 (UTC) | Creates a string containing the universal date and the time in ISO-8601 format. |
If custom format is selected, the target string can be formatted via the text box. There are special tokens/placeholders which will be replaced by the corresponding values. Arbitrary text that contains token characters must be enclosed in square brakets to escape the tokens. The supported tokens are described below:
| Token | Description |
|---|---|
NNNN |
Era name |
N/NN/NNN
|
Era name, abbreviated |
NNNNN |
Era name, narrow |
y |
Era year (1, 2, 3, ..., 2020, ...) |
Y |
ISO 8601 year (1970, 1971, ..., 9999, +10000, +10001, ...) |
YY |
2-digit year (70, 71, ..., 29, 30, ...) |
YYYY |
4-digit year (1970, 1971, ..., 2029, 2030, ...) |
YYYYYY |
Expanded year (full time range of 273970 years, 0 padded) |
gg |
2-digit week year (70, 71, ..., 29, 30, ...) |
gggg |
4-digit week year (1970, 1971, ..., 2029, 2030, ...) |
GG |
2-digit ISO week year (70, 71, ..., 29, 30, ...) |
GGGG |
4-digit ISO week year (1970, 1971, ..., 2029, 2030, ...) |
Q |
Quarter (1, 2, 3, 4) |
Qo |
Ordinal quarter (1st, 2nd, 3rd, 4th) |
M |
Month number (1, 2, ..., 11, 12) |
MM |
Month number, 0 padded (01, 02, ..., 11, 12) |
MMM |
Month name, abbreviated (Jan, Feb, ..., Nov, Dec) |
MMMM |
Month name (January, February, ..., November, December) |
w |
Weak of year (1, 2, ..., 52, 53) |
ww |
Weak of year, 0 padded (01, 02, ..., 52, 53) |
wo |
Ordinal weak of year (1st, 2nd, ..., 52nd, 53rd) |
W |
ISO weak of year (1, 2, ..., 52, 53) |
WW |
ISO weak of year, 0 padded (01, 02, ..., 52, 53) |
Wo |
Ordinal ISO weak of year (1st, 2nd, ..., 52nd, 53rd) |
d |
Day of week as number (0, 1, ..., 5, 6) |
dd |
Day of week as name, 2-letter abbreviated (Mo, Tu, ..., Sa, Su) |
ddd |
Day of week as name, 3-letter abbreviated (Mon, Tue, ..., Sat, Sun) |
dddd |
Day of week as name (Monday, Tuesday, ..., Saturday, Sunday) |
do |
Day of week as ordinal number (0th, 1st, ..., 5th, 6th) |
e |
Day of week as region specific number (0-6 or 1-7) |
E |
Day of week as ISO number (1, 2, ..., 6, 7) |
D |
Day of month (1, 2, ..., 30, 31) |
DD |
Day of month, 0 padded (01, 02, ..., 30, 30) |
Do |
Ordinal day of month (1st, 2nd, ..., 30th, 31st) |
DDD |
Day of year (1, 2, ..., 364, 365) |
DDDD |
Day of year, 0 padded (001, 002, ..., 364, 365) |
DDDo |
Ordinal day of year (1st, 2nd, ..., 364th, 365th) |
h |
12h hour (1, 2, ..., 11, 12) |
hh |
12h hour, 0 padded (01, 02, ..., 11, 12) |
H |
24h hour (0, 1, ..., 22, 23) |
HH |
24h hour, 0 padded (00, 01, ..., 22, 23) |
k |
24h hour, 1 based (1, 2, ..., 23, 24) |
kk |
24h hour, 1 based, 0 padded (01, 02, ..., 23, 24) |
m |
Minute (0, 1, ..., 58, 59) |
mm |
Minute, 0 padded (00, 01, ..., 58, 59) |
s |
Second (0, 1, ..., 58, 59) |
ss |
Second, 0 padded (00, 01, ..., 58, 59) |
S |
1/10th of a second (0, 1, ..., 8, 9) |
SS |
1/100th of a second (00, 01, ..., 98, 99) |
SSS |
Millisecond (000, 001, ..., 998, 999) |
SSSS ... SSSSSSSSS
|
Fractional second (000[0...], 001[0...], ..., 998[0...], 999[0...]) |
a |
Period, lower case (am, pm) |
A |
Period, upper case (AM, PM) |
z, zz
|
Abbreviated time zone name (EST, CST, ..., MST, PST) |
Z |
Time zone offset (-07:00, -06:00, ..., +06:00, +07:00) |
ZZ |
Time zone offset, compact (-0700, -0600, ..., +0600, +0700) |
x |
Unix epoch timestamp in milliseconds |
X |
Unix epoch timestamp in seconds |
l |
Region-specific numeric date |
L |
Region-specific numeric date, 0 padded |
ll |
Region-specific date with abbreviated month names |
LL |
Region-specific date with month names |
lll |
Region-specific date with abbreviated month names and time |
LLL |
Region-specific date with month names and time |
llll |
Region-specific date with abbreviated month names, abbreviated week day names and time |
LLLL |
Region-specific date with month names, week day names and time |
LT |
Region-specific time |
LTS |
Region-specific time with seconds |
Region-specific formats and translations for names of days, months etc. are depending on the current locale of the Node-RED host. Please note the limitations for supported regions as stated on the main page.
Regional date/time strings can look like the following
"24.03.2024 16:20:57" // German format
"03/24/2024 4:20:57 PM" // US formatRelative time strings can look like the following:
// past
"a few seconds ago"
"a minute ago"
"5 minutes ago"
"an hour ago"
"10 hours ago"
"a day ago"
"6 days ago"
"a month ago"
"3 months ago"
"a year ago"
"8 years ago"
// future
"in a few seconds"
"in a minute"
"in 5 minutes"
"in an hour"
"in 10 hours"
"in a day"
"in 6 days"
"in a month"
"in 3 months"
"in a year"
"in 8 years"Calendar strings can look like the following:
"Last Monday at 2:30 AM" // last week
"Yesterday at 2:30 AM" // the day before
"Today at 2:30 AM" // the same day
"Tomorrow at 2:30 AM" // the next day
"Sunday at 2:30 AM" // the next week
"7/10/2011" // far awayISO-8601 strings can look like the following:
"2024-03-24T16:20:57.684+01:00" // local time
"2024-03-24T15:20:57.684Z" // universal timeA custom string with format [Today is] dddd, MMMM Do YYYY, h:mm:ss a can look like the following:
"Today is Sunday, March 24th 2024, 4:20:57 pm"In the second row, it is possible to configure the local time of the target value:
| Selection | Description |
|---|---|
| current time zone | The original time zone (i.e., the time zone configured in the associated configuration node) is kept unmodified. |
| time zone | The name of a valid time zone identifier can be specified and the time is converted to that time zone. |
| UTC offset | An offset in minutes and/or hours can be specified, which is applied as offset to the universal time. |
The UTC offset can be specified in the following ways:
| Type | Format | Description |
|---|---|---|
| Number | -16 ≤ n ≤ 16 | UTC offset as number of hours. |
| Number | n < -16 or n > 16 | UTC offset as number of minutes. |
| String |
+HH:MM or -HH:MM
|
UTC offset as combination of hours and minutes. |
Converts the target timespan to a specific number or string representation. The following possibilities are supported:
| Selection | Description |
|---|---|
| numeric format | The timespan is represented as single number in various units, see below for unit description. |
| string format | The timespan is represented as string in various formats, see below for format description. |
| custom format | The timespan is represented as string in a custom format, see below for possible formatting options. |
If numeric format is selected, the unit can be chosen from the dropdown list. In the second row, the precision of the target number can be specified.
| Selection | Description |
|---|---|
| integer number | The numeric value is an integer value that is either rounded, rounded up or rounded down. |
| floating point number | The numeric value is a floating point value whose maximum number of decimal places can be specified (0 means no limit). |
If string format is selected, one of the following formats can be selected from the dropdown list:
| Selection | Description |
|---|---|
| timespan | Creates a string containing a timespan in the form d.hh:mm:ss. |
| timespan (1/10 of a second) | Creates a string containing a timespan with 10th fractions of a second in the form d.hh:mm:ss.S. |
| timespan (1/100 of a second) | Creates a string containing a timespan with 100th fractions of a second in the form d.hh:mm:ss.SS. |
| timespan (milliseconds) | Creates a string containing a timespan with milliseconds in the form d.hh:mm:ss.SSS. |
| textual timespan | Creates a string containing a textual representation of the duration, being less precise the longer it is. |
| ISO‑8601 | Creates an ISO-8601 duration string. |
For timespan strings, single portions will be omitted if these and all more significant portions are 0. For instance, a duration of 275628 milliseconds (4 minutes, 35 seconds and 628 milliseconds) will be represented by the string "04:35.628". On the other hand, if the duration is for instance 259475628 milliseconds (2 days, 4 minutes, 35 seconds and 628 milliseconds), it will be represented by the string "3.00:04:35.628".
If custom format is selected, the target string can be formatted via the text box. There are special tokens/placeholders which will be replaced by the corresponding values. Arbitrary text that contains token characters must be enclosed in square brakets to escape the tokens. The supported tokens are described below:
| Token | Description |
|---|---|
y |
Number of full years |
M |
Number of full months (0, 1, ..., 10, 11) |
w |
Number of full weeks (0, 1, 2, 4) |
d |
Number of full days (0, 1, ..., 29, 30) |
h |
Number of full hours (0, 1, ..., 22, 23) |
hh |
Number of full hours, 0 padded (00, 01, ..., 22, 23) |
m |
Number of full minutes (0, 1, ..., 58, 59) |
mm |
Number of full minutes, 0 padded (00, 01, ..., 58, 59) |
s |
Number of full seconds (0, 1, ..., 58, 59) |
ss |
Number of full seconds, 0 padded (00, 01, ..., 58, 59) |
S |
Number of full 1/10th of a second (0, 1, ..., 8, 9) |
SS |
Number of full 1/100th of a second (00, 01, ..., 98, 99) |
SSS |
Number of milliseconds (000, 001, ..., 998, 999) |
Timespan strings can look like the following:
"2.07:25:54.235"Textual timespan strings can look like the following:
"a few seconds"
"a minute"
"5 minutes"
"an hour"
"10 hours"
"a day"
"6 days"
"a month"
"3 months"
"a year"
"8 years"ISO-8601 duration strings can look like the following:
"P2Y8M12DT4H21M52S"A custom string with format [The event starts in] y [years], m [months], d [days], h [hours], m [minutes and] s [seconds] can look like the following:
"The event starts in 2 years, 8 months, 12 days, 4 hours, 21 minutes and 52 seconds"Incoming messages act as trigger for executing the configured rules and are modified if there are change rules containing message property based targets.
The output port forwards any incoming, possibly modified, message.