The Data Trigger Module

With the Data Trigger module you can monitor any number of data sources and trigger actions based on the data. The module uses a list of trigger definitions to analyze the data. When new data is received the trigger conditions are validated and when the conditions for a trigger are met an output message is sent. These messages can then be used to trigger actions, like creating a work order or sending a notification.

Trigger definitions

A trigger definition contains the following:

• Unique ID
• Name
• List of conditions
• Metadata

The metadata section is used to add information associated with this trigger, to be used by downstream processing. For example ‘Workorder ID’ or ‘email address’ to send notifications to. The output messages contain the ID, name, metadata and timestamps.

Trigger conditions

Each trigger definition can contain any number of conditions. When multiple conditions are used they can be combined using ‘AND’ (all must be true) or ‘OR’ (at least one must be true). It is also possible to fire the trigger immediately when the conditions are met (leading edge) or when the conditions fall back to being false (trailing edge).

A condition is similar to the message filters that are available on all modules. A condition can check the value of a single property using one of the available operators (e.g. ‘IsTrue’, ‘GreaterThan’, ‘Contains’). The data can be checked against a static value, e.g. ‘temp > 5’ or against another property value, e.g. ‘temp1 > temp2’.

There are two additional features, not available in message filters:

• Combine two values using basic arithmetic operations (add, sub, mul, div) and apply the condition on the result, e.g. ‘temp1 - temp2 > 5’
• Apply a timing requirement, e.g. ‘temp1 > 5 for more than 10 seconds’

Data formats

Input data can be either messages with a single value in each message object, or an array of message objects. Timestamps can be provided with each message, for all messages in an array, or be set by the module based on arrival time (see ‘Time handling’ below). Two formats are supported for providing data, based on the module configuration:

{
    “source”: “temp1”,
    “value”: 5
}

{
    “temp1”: 5
}

All messages must use the same format.

{
    “temp1”: 5
}

{
    “temp2”: 95
}

{
    “temp1”: 6
}

In this case the trigger will fire when the last message is received, since this value fulfills the first condition (‘temp1 > 5’) and the last known value of ‘temp2’ is 95 (fulfilling the second condition: ‘temp2 < 100’). The ‘triggerTimestamp’ in the output message will be set to the time associated with the last message (see below).

Time handling

To support duration based conditions the module keeps track of when a condition changes state. It therefore needs to keep track of the time.

Each data point is associated with a timestamp, either by providing it with the data, or by using the arrival time. Each condition has its own ‘clock’ which is progressed each time new data is received for any of the data points used in the condition. This internal ‘clock’ is then used to evaluate duration conditions, e.g. if a condition becomes true at ‘12:00:00’ and there is a duration requirement of 60 seconds, the trigger will fire whenever a message is received with a timestamp beyond ‘12:01:00’. The ‘triggerTimestamp’ in the output message will be set to the timestamp of the message that caused the trigger to ‘fire’. Let’s see an example, assuming the following condition: ‘temp1 > 5 for 60 seconds’ and the following sequence of messages:

{
    “temp1”: 6,
    “timestamp”: “12:00:00”
}

{
    “temp2”: 95,
    “timestamp”: “12:01:00”
}

{
    “temp1”: 7,
    “timestamp”: “12:02:00”
}

In this case the trigger will fire when the last message is received. The message with ‘temp2’ data will not progress the ‘clock’ for this condition, since ‘temp2’ is not used.

Samples

Below is an example of a complete trigger definition and the corresponding output message when this trigger fires.

Trigger definition

{
  "id": "42fae9bb-fc80-4944-9776-91c7a1797c0f",
  "name": "Temp too high",
  "logicOperation": "And",
  "edge": "Leading",
  "conditions": [
    {
      "sourceProperty": "temp1",
      "condition": "GreaterThan",
      "value": 5,
      "durationInSeconds": 60
    },
    {
     "sourceProperty": "temp2",
     "condition": "LessThan",
     "value": 100,
     "durationInSeconds": 60
    }
  ],
  "metadata": {
    "notifyEmail": "support@crosser.io",
    "message": "Temp too high on machine X"
  }
}

Trigger message

{
  "id": "42fae9bb-fc80-4944-9776-91c7a1797c0f",
  "metadata": {
    "notifyEmail": "support@crosser.io",
    "message": "Temperature too high on machine X"
  },
  "name": "Temp too high",
  "timestamp": "2024-06-13T13:03:28.814+00:00",
  "triggerTimestamp": "2024-06-13T11:00:01.701+00:00"
}

Note: The ‘timestamp’ property holds the time when the trigger message was sent. The ‘triggerTimestamp’ property holds the timestamp associated with the data that caused the trigger to fire.