On Message State Change
AMPS provides two modules, amps-action-on-alert and amps-action-on-message-condition-timeout, to run an action when a message in a SOW topic meets a specific condition for longer than a specified period of time. These modules provide a way to track specific messages in a SOW topic and indicate whether the message has timed out (that is, been in the monitored state longer than expected) or whether the message has been processed as expected and is no longer being tracked within the specified timeout.
The amps-action-on-alert action monitors a SOW topic for messages that match a filter and triggers an action when either:
The message has remained matched on the filter for at least the specified duration (indicating a timeout), or
An out-of-focus message is received for the message (indicating that the message is no longer tracked)
The amps-action-on-message-condition-timeout action monitors a SOW topic for messages that match a filter and triggers an action when:
The message has remained matched on the filter for at least the specified duration (indicating a timeout)
Use amps-action-on-message-condition-timeout if only timeouts are important, otherwise use amps-action-on-alert if both timeouts and message tracking are important.
For example, a set of actions might be configured to publish a message to an Alerts topic if an order is unprocessed for more than a specified timeout. When the order is processed, the actions might publish a message to a Statistics topic for tracking purposes. Rather than creating two independent actions, which could lead to overlap if the order is processed at the same time that the alert is being generated, use this action to guarantee that only one of the events will be generated.
The module tracks each message that matches the filter individually, and will run once for each message tracked.
This module uses the Out-of-Focus notification (OOF) mechanism. When a message matches the specified topic and filter, the module begins tracking that message. If no OOF notification is received for that message within the specified timeout, the action runs for that message and indicates that the timeout has been exceeded. If an OOF notification is received before the timeout expires, then the action runs for that message, indicating that the message is no longer tracked.
This module uses the custom event system as a way of indicating whether a given message was removed from tracking, or whether the message timed out. When configuring the action, you specify the event to raise for each of these states. This module stores the exact event raised in a context variable, which you can then use with amps-action-do-event to raise the event.
While the AMPS server is running, this action will trigger exactly once for each message after it reaches the timeout period. When AMPS restarts, if a message that had previously triggered this action still exists in the SOW topic (and still matches the filter provided, if any), the action will run for that message immediately after the module initializes on restart.
This action requires the following parameters. In addition to that, this module also accepts the optional parameters listed below:
| Parameter | Description |
|---|---|
| The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be either a SOW topic, a view or a conflated topic. Queues are not supported. There is no default for this parameter. |
| The message type of the topic to monitor for messages. There is no default for this parameter. |
| The value to store when an out-of-focus notification is received for a tracked message. There is no default for this parameter. |
| The value to store when a message is in the tracked state for longer than the timeout period. There is no default for this parameter. |
| The name of the context variable in which to store the reason that the action is running (either the string in There is no default for this parameter. |
| The amount of time to wait for an OOF notification for the message before running the action. |
| Sets the filter to apply. Only messages that match this filter will be monitored by this action. If no filter is provided, every message of the specified message type in topics that match the |
The module adds the following variables to the AMPS context:
| Variable | Description |
|---|---|
| The topic of the message that triggered the alert. |
| The current data of the message. |
| The length of the current data of the message, in bytes. |
| The bookmark of the message. Empty if there is no bookmark for the message. |
| The timestamp at which the module began tracking the message. |
| The client name of the current value of the message. |
| The current SowKey for the message. |
The variable specified in | The reason the action is running. This will be either the value of |
Last updated