Notification strategy

A notification strategy determines the timing and frequency with which to send notifications.

Note: Devices that were created for Maximo® Monitor 8.8 and later do not use logical or physical interfaces.

With a notification strategy in place you ensure that notifications are sent when data is outside of normal ranges and conditions. You also use the strategy to control the number of alerts that are triggered for a rule over a period of time.

For example, you can set it up so that when the temperature of the device spikes for a specified amount of time, an alert is sent to the dashboard on a user's device, and an email is sent to the administrator.

Notifications can be sent every time the conditions that are specified in a notification rule are met, only the first time they are met, when they are met a certain number of times, or when they are met for a certain duration.

You set the strategy by selecting notification criteria in the dashboard when configuring a notification rule, or by setting the notificationStrategy parameter when configuring a rule using the API.

Use the following notification criteria when you configure rules:

Every time

The every-time notification strategy triggers a rule notification every time the rule evaluates as true. The notification strategy for a rule defaults to every-time if a notification strategy is not specified.

The following example shows how to set the every-time notification strategy:

{
    "name": "Temperature Too High Rule",
    "condition": "$state.currentTemperature > $instance.metadata.maxTemperatureThreshold",
    "logicalInterfaceId": "5c8f7357e42f4900265bf579",
    "id": "5c8f959fe42f4900265bf583",
    "notificationStrategy": {
        "when": "every-time"
    },
    "version": "active",
    "created": "2019-03-18T12:57:03Z",
    "createdBy": "john.doe@us.ibm.com",
    "updated": "2019-03-27T14:44:31Z",
    "updatedBy": "fred.bloggs@uk.ibm.com",
    "refs": {
        "logicalInterface": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579",
        "self": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579/rules/5c8f959fe42f4900265bf583"
    }
}

Becomes true

The becomes-true notification strategy is used to trigger a rule notification the first time the rule evaluates as true. Subsequent messages that also evaluate as true do not trigger notifications. When the rule condition evaluates to false, the context is reset so that a rule notification is triggered the next time that the rule evaluates as true.

The following example shows how to set the becomes-true notification strategy:

{
    "name": "Temperature Too High Rule",
    "condition": "$state.currentTemperature > $instance.metadata.maxTemperatureThreshold",
    "logicalInterfaceId": "5c8f7357e42f4900265bf579",
    "id": "5c8f959fe42f4900265bf583",
    "notificationStrategy": {
        "when": "becomes-true"
    },
    "version": "active",
    "created": "2019-03-18T12:57:03Z",
    "createdBy": "john.doe@us.ibm.com",
    "updated": "2019-03-27T14:44:31Z",
    "updatedBy": "fred.bloggs@uk.ibm.com",
    "refs": {
        "logicalInterface": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579",
        "self": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579/rules/5c8f959fe42f4900265bf583"
    }
}

Persists

The persists notification strategy is used to trigger a rule notification if the rule persists as true for the specified amount of time, such as 60 seconds. You must also set the timePeriod value when configuring a persists notification strategy.

Note: The time period must be set in seconds and the maximum value is 604,800 seconds, which represents 1 week.

The time period starts when the rule condition initially evaluate to true. The rule notification is only published after the time period expires. When the rule condition evaluates to true again, a new time period starts. If the rule condition evaluates to false during an active time period, the time period expires. The rule condition can evaluate to false multiple times and restarts when it is true again.

Note: The IoT tool does not detect when the time period has expired automatically. Because rules are event-driven, the IoT tool is only able to check if the time period has expired when it processes the next event. As a result, you should choose a value for the time period that allows multiple device events to be processed within it.

The following information example shows how to set the persists notification strategy:

{
    "name": "Temperature Too High Rule",
    "condition": "$state.currentTemperature > $instance.metadata.maxTemperatureThreshold",
    "logicalInterfaceId": "5c8f7357e42f4900265bf579",
    "id": "5c8f959fe42f4900265bf583",
    "notificationStrategy": {
        "when": "persists",
        "timePeriod": 60
    },
    "version": "active",
    "created": "2019-03-18T12:57:03Z",
    "createdBy": "john.doe@us.ibm.com",
    "updated": "2019-03-27T14:44:31Z",
    "updatedBy": "fred.bloggs@uk.ibm.com",
    "refs": {
        "logicalInterface": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579",
        "self": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579/rules/5c8f959fe42f4900265bf583"
    }
}

X in Y

The x-in-y notification strategy triggers a notification event if the rule evaluates as true X number of times in Y amount of time. You must also set the count value and the timePeriod value when configuring an x-in-y notification strategy.

Note: The maximum count value is 1000. The time period must be set in seconds, and the maximum value is 604,800 seconds, which represents 1 week.

The time period starts when the rule condition initially evaluates to true. A rule notification is published if the rule condition evaluates to true the specified number of times within the time window. Subsequent true evaluations in the same time window do not result in the publication of a rule notification. After the time period ends, a new time period starts when the rule condition next evaluates to true. If the rule condition does not evaluate to true the specified number of times in a time period, no rule notification is published.

For example, the rule can be configured to trigger if the conditions are met four times in 30 minutes. The device sends one new message every five minutes. At noon, the temperature initially exceeds 90 degrees, which meets the condition. The time period begins, but the rule is not yet triggered. After 15 minutes and three more messages that indicate that the temperature exceeded 90 degrees are received, the rule is triggered. The rule is then not triggered for another 15 minutes regardless of the temperature.

The following information example shows how to set the X in Y notification strategy:

{
    "name": "Temperature Too High Rule",
    "condition": "$state.currentTemperature > $instance.metadata.maxTemperatureThreshold",
    "logicalInterfaceId": "5c8f7357e42f4900265bf579",
    "id": "5c8f959fe42f4900265bf583",
    "notificationStrategy": {
        "when": "x-in-y",
        "count": 5,
        "timePeriod": 60
    },
    "version": "active",
    "created": "2019-03-18T12:57:03Z",
    "createdBy": "john.doe@us.ibm.com",
    "updated": "2019-03-27T14:44:31Z",
    "updatedBy": "fred.bloggs@uk.ibm.com",
    "refs": {
        "logicalInterface": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579",
        "self": "/api/v0002/logicalinterfaces/5c8f7357e42f4900265bf579/rules/5c8f959fe42f4900265bf583"
    }
}