Time Filter Node

The time filter node is similar to the time switch node but instead of routing messages to different output ports, it forwards or discards messages depending on different conditions.

Configuration

On the configuration page, various settings of the node can be configured.

General

Name

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.

Configuration

The configuration node to be used must be selected here.

Base Time

The base time specifies the time that is compared with the operands of the conditions. Different sources for the base time can be selected via the popup menu:

The following tables explains the selection possibilities:

Selection	Description
message ingress	Base time is the ingress time of the input message.
global.	Base time is taken from a global context variable.
flow.	Base time is taken from a flow context variable.
msg.	Base time is taken from a message property.

The format for the context variables or message properties containing the base time must be according to the basic format as described in section Time Input. For time-only values the date of the current day is applied.

Evaluation

Specifies the evaluation method for forwarding messages based on the results of the conditions.

The following table describes the possible evaluation methods:

Selection	Description
logical OR	The message is forwarded if at least one of the conditions evaluates to true.
logical AND	The message is forwarded only if all conditions evaluate to true.
annotation	The message is annotated and always forwarded. Evaluation of the condition results must be performed outside of the node.
expression	The message is forwarded if the specified JSONata expression evaluates to true.

Annotation Mode

If annotation is selected, incoming messages are forwarded in any case and the evaluation result of each condition is stored as an array of boolean values in property msg.evaluation. If the message already contains a property with this name, it is renamed to msg._evaluation.

The annotaton mode is useful in case that the evaluation of the condition results should be performed outside of the filter node. In this case, a function node can be connected downstream in order to handle the results of the configured conditions.

JSONata Expression

If expression is selected, a JSONata expression can be specified in order to perform enhanced evaluation of the condition results. The JSONata expression must result in a boolean value, otherwise an error is emitted. If the expression evaluates to true, the message is forwarded, in case of false, it is discarded.

In the JSONata expression, the results of the conditions can be accessed through the variable $condition which is an array of boolean values. Additionally all properties from the input message can be queried for including them in the evaluation.

The purpose of the JSONata expression is solely to evaluate the filter result, it can not be used to change properties of the input message.

Examples

($condition[0] or $condition[1]) and $condition[2]

($condition[0] and $not($condition[1])) or $condition[2]

$condition[3] and (topic = "lights")

Conditions

The conditions are evaluated against the configured base time. 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:

Operator

The operator defines the type of operands which are used to evaluate the condition. The provided possibilities are described in more detail in the following table.

Selection	Description
==	This operator checks if the base time is equal to the specified time.
!=	This operator checks if the base time is not equal to the specified time.
before	This operator checks if the base time is earlier than the specified time.
until	This operator checks if the base time is earlier than or equal to the specified time.
since	This operator checks if the base time is equal to or later than the specified time.
after	This operator checks if the base time is later than the specified time.
between	This operator checks if the base time is equal to or later than the first and earlier than or equal to the second specified time.
outside	This operator checks if the base time is earlier than the first or later than the second specified time.
days	This operator checks if the base time matches special days of a month.
week days	This operator checks if the base time matches one of the selected week days.
months	This operator checks if the base time matches one of the selected months.

Operands

For operators ==, !=, before, until, since and after a single comparison time and for operators between and outside two comparison times have to be specified as described in section Time Input. Additionally to what is described there, time filter 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 base time is applied.

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 base time is applied.

When clicking on the expand/collapse arrow on the right side of some of the operands, an additional row appears. Here, an (optionally randomized) offset and the precision for the comparison corresponding to the operand can be configured.

The offset will be added to or subtracted from the operand time and must be entered in minutes in the range of -300 to +300. If the checkbox to the right of the offset is selected, the offset will be randomized between 0 and the specified value. The precision specifies the least significant part of the operand's date and time that will be considered at most for the comparison. E.g., when selecting millisecond (the default), all parts from year up to millisecond will be considered. Selecting for instance hour will only consider the year, the month, the day and the hour, but not the minute, the second and the millisecond.

If the second time is equal to or before the first time and both times have no explicitly provided date (and hence, the date of the base time is applied), one day is added to the second time, 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.

For operator days the type of days can be selected from the dropdown box. The provided possibilities are described in more detail in the following table.

Selection	Description
first	Matches the first week day, day, workday or weekend day of the month.
second	Matches the second week day of the month.
third	Matches the third week day of the month.
fourth	Matches the fourth week day of the month.
fifth	Matches the fifth week day of the month.
last	Matches the last week day, day, workday or weekend day of the month.
even days	Matches all even days of the month.
specific day	Matches a specific day of a specific month or of every month.

The conditions can be negated by selecting the Exclude (⊘) checkbox.

For days types first, second, third, fourth, fifth and last the related day has to be selected:

Selection	Applicable to	Description
MO .. SU	all	Matches the selected day of the week.
day	first, last	Matches any day.
workday	first, last	Matches a day of the workweek (Monday to Friday).
weekend day	first, last	Matches a day of the weekend (Saturday and Sunday).

For days type specific the day of the month has to be entered and the month has to be selected:

Selection	Description
JAN .. DEC	Matches the selected month.
any	Matches any month.

For operator week days each day of a week can be selected or cleared.

For operator months each month of a year can be selected or cleared.

Source

The source group specifies the data source for the condition. The provided possibilities are described in more detail in the following table.

Selection	Description
expression	The condition result is taken from the provided JSONata expression.
context	The condition is loaded from an enviroment or a context variable.

When selecting expression in the source group of the dropdown menu, a JSONata expression must be specified which must result in a boolean value. All properties from the input message can be accessed and the base time is available through the variable $baseTime. Additionally there are some common expression variables and function extensions provided, see JSONata Expressions for details.

When selecting context in the source group of the dropdown menu, an environment variable or a global or flow context variable can be specified from which the condition as a whole will be loaded at runtime. This allows dynamic configuration of one or more conditions and is useful when using the node in a sub flow or if the data for the conditions should be retrieved from a runtime source like e.g., a Node-RED dashboard UI. In contrast to the functionality described in section Operands above to retrieve single times from environment or context variables, here you can specify whole conditions including offsets for time-based operators as well as days, week days and months operators in such variables. The content of the variables is loaded on message ingress and must be an object with the following properties:

Property	Type	Description
operator	String	The operator for comparison, which can be one of "equal", "notEqual", "before", "until", "since", "after", "between", "outside", "days", "weekdays" or "months".
operands	Object, Array	The operand(s) for comparison, see below for content.

If operator is:

• "equal", "notEqual", "before", "until", "since" or "after", operands must be an object.
• "between" or "outside", operands must be an array containing two objects corresponding to the first and second operand.

Above mentioned objects must follow the structured input format as described in section Time Input. Additionally, the operand object may contain the property precision. The property must be a string and can be one of "millisecond", "second", "minute", "hour", "day", "month" or "year".

If operator is "days", operands must be an object containing the following properties:

Property	Type	Description
type	String	The operand type, which can be one of "first", "second", "third", "fourth", "fifth", "last", "even" or "specific".
day	String, Number	Depending on the operand type the name of a day ("monday", "tuesday", ..., "sunday", "day", "workday" or "weekend") or the day of the month as number. This property is not applicable for type "even".
month	String	The name of the month ("january", "february", ...). This property is only applicable for type "specific" and optional. When omitted, condition matches for any month.
exclude	Boolean	When set to true, the result of the condition will be negated.

If operator is "weekdays", operands must be an object. It may contain boolean properties with names of days of the week. If true, the condition is fullfilled for base times on that day or not fulfilled if the property is false or not present.

If operator is "months", operands must be an object. It may contain boolean properties with names of months of the year. If true, the condition is fullfilled for base times in that month or not fulfilled if the property is false or not present.

Examples

The following examples are JSON representations of context variables as they can be loaded by the time filter node.

Condition evaluates to true if base time is before sunrise:

{
    "operator": "before",
    "operands":
    {
        "type":   "sun",
        "value":  "sunrise",
        "offset": 0,
        "random": false
    }
}

Condition evaluates to true if base time is between sunset minus 15 minutes (randomized) and 22:30:

{
    "operator": "between",
    "operands":
    [
        {
            "type":      "sun",
            "value":     "sunset",
            "offset":    -15,
            "random":    true,
            "precision": "minute"
        },
        {
            "type":      "time",
            "value":     "22:30",
            "offset":    0,
            "random":    false,
            "precision": "minute"
        }
    ]
}

Condition evaluates to true if base time is on the last working day of the month:

{
    "operator": "days",
    "operands":
    {
        "type":    "last",
        "day":     "workday",
        "exclude": false
    }
}

Condition evaluates to true if base time is not on the 12th of October:

{
    "operator": "days",
    "operands":
    {
        "type":    "specific",
        "day":     12,
        "month":   "october",
        "exclude": true
    }
}

Condition evaluates to true if base time is on a weekend:

{
    "operator": "weekdays",
    "operands":
    {
        "saturday": true,
        "sunday":   true
    }
}

Condition evaluates to true if base time is between october and march:

{
    "operator": "months",
    "operands":
    {
        "january":  true,
        "february": true,
        "march":    true,
        "october":  true,
        "november": true,
        "december": true
    }
}

Input

Incoming messages are either forwarded to the output port or discarded.

Outputs

If one or multiple conditions match the configured base time according to the specified evaluation method, the message is sent out. Otherwise it is discarded.