Alerting

Created Montag 13 April 2015

Analysis

UCS documentation specifies 2 interfaces related to Alerting:

1. Alerting Interface: alert clients can update the state of an alert.
2. UCS Alerting Interface: client side interface to receive alert-related events from UCS server.

According to the documentation, the following is a usual "Send Alert with ACK" scenario:

The "send message" path is clear. A Sender uses Client.sendMessage() to send a new AlertMessage to UCS. UCS uses a specific adapter to send the message to one or more Receivers. (Note that our NiFi implementation will not have any adapter for the alerting part. All the messages will be kept inside UCS).
When the Receiver wants to ACK the message it uses UCSAlerting.updateAlertMessage() (Note: it is not clear what are the parameters the Receiver uses for the invocation) to modify the status of the AlertMessage in UCS. UCS then notifies the clients using, according to the documentation UCSClient.handleResponse() method. This is where I think the documentation is wrong. The method that UCS should use to notify a client about a modification in an AlertMessage should be UCSAlerting.updateAlertMessage(). This analysis document will use UCSAlerting.updateAlertMessage() and not UCSClient.handleResponse() to notify client about a modification in an AlertMessage.

UCSClient.receiveMessage vs UCSAlerting.receiveAlertMessage

The documentation doesn't specify what is the specific sequence of actions when a new AlertMessage is introduced in UCS via Client.sendMessage(). The singularity of this situation is that there are 2 "UCS" interfaces that has to be invoked here: UCSClient.receiveMessage() and UCSAlerting.receiveAlertMessage(). Given that the documentation is not specific, our NiFi implementation will notify both interfaces whenever a new AlertMessage is introduced in UCS.

AlertStatus vs AlertStatusByReceiver.

Another gray area in the documentation is what is the correct usage of alertStatus and statusByReciever properties of AlertMessageHeader class. Apparently, an AlertMessage has 2 levels of statuses: a global status and a specific status for each of the recipients. It is not clear how/if the global status is related in any way with each of the individual statuses of each of the recipients. Both levels are defined by the same enum: AlertStatus.

public enum AlertStatus {

Acknowledged,
   New,
   Expired,
   Retracted,
   Pending

}

Our NiFi implementation will use these 2 levels of statuses in the following way:

• alertStatus: it will only allow the following values: New, Pending, Acknowledged and Retracted. Any incoming message will start with a 'New' status. When a Receiver acknowledges the message, its status will be modified to Pending (if there are more Recipients that haven't yet acknowledged the message) or Retracted (If the recipient is the only recipient of the message or if all the recipients of the message already aknowledged it). When an AlertMessage is canceled, its status is changed to Retracted.
• statusByReciever: it will only allow the following values: Pending and Acknowledged. When a new AlertMessage arrives to UCS, it must contain one entry in this Map with a status of Pending for each of the message's recipients. When a recipient acknowledges an AlertMessage, it changes his own status to Acknowledged. UCS will analyze and update the global status whenever a statusByReceiver is modified.

UCSAlerting methods

This section explains when each the methods of UCSAlerting are invoked by UCS.

receiveAlertMessage

This method is invoked whenever a new AlertMessage arrives to UCS. Usually, an AlertMessage is introduced into UCS using Client.sendMessage().

updateAlertMessage

This method is invoked whenever an AlertMessage is updated in UCS. An AlertMessage is modified using UCSAlerting.updateAlertMessage().
Note: Client interface also defines a method called updateMessage, but the intention of this method is to update a message that is being prepared BEFORE it is actually sent to UCS. In the current NiFi implementation, Client.updateMessage is not related in any way with UCSAlerting.updateAlertMessage.

cancelAlertMessage

Is is not clear in the documentation what is the action in UCS that triggers this method. Client interface defines a method called cancelMessage but this method is used to cancel a message that was being prepared BEFORE it was actually sent to UCS.
A way this method could be triggered is when a client uses Alerting.updateAlertMessage() specifying a status of Retracted. We need to investigate further.

Sequence Diagrams

Send and receive an Alert Message

Send an Alert Message and change its status

Send an Alert Message and cancel it

Design

Alerting Interface Design

The Alerting interface is similar to the Client interface already implemented in UCS. This interface is a one-way mechanism to execute a command on UCS. The available command in our NiFi implementation will be: updateAlertMessage.
An option for the implementation of this interface is to implement it as a specific command inside Client workflow.
A specific processor must be implemented to hold the logic related to this operation: UCSUpdateAlertMessage.

UCSAlerting Interface Design

The UCSAlerting interface is similar to the UCS Client Interface already implemented in UCS. Before this interface is enabled for a client, it must be registered into UCS (like UCSRegisterUCSClientCallback in Client Interafce workflow is currently doing).
A new UCSRegisterUCSAlertingCallback processor must be implemented to allow clients to register themselves as a UCSAlerting client. UCSControllerService must be modified to hold these references.

Whenever an AlertMessage is created/modified/canceled in UCS, all the UCSAlerting clients that are currently registered must be notified. This is something similar to what UCS Client Interface workflow is currently doing. A new processor called UCSGetUCSAlertingCallbacks must be created to retrieve any registered UCSAlerting client from UCSControllerService (similar to what UCSGetUCSClientCallbacks is currently doing).

New Workflow/s

Depending whether we decide to re-use Client Interface workflow or not, one or two new workflows must be implemented.

Re-use Client Interface Workflow

If we decide to re-use Client Interface workflow then we need to introduce a new processor into this workflow: UCSUpdateAlertMessage. This processor will implement the required logic to update an Alert Message into UCS. A new output port must be added to this workflow so other parts of UCS can be notified about the modification of an Alert Message (i.e. UCS Alerting Interface workflow).

In order to allow clients to register UCSAlerting callback interfaces into UCS, a new processor must be implemented and added into Client Interface workflow: UCSRegisterAlertingCallback.

The previous image shows how Client Interface workflow will look after the modifications for the Alerting Interface are implemented.

Implement new Alerting Interface

In this approach, the two previously mentioned processors - UCSUpdateAlertMessage and UCSRegisterAlertingCallback - are implemented into a specific workflow called "Alerting Interface". The structure of this workflow is similar to the Client Interface.

As you can see in the previous image, the new workflow has a similar structure to Client Interface: a message is received via HTTP, parsed and processed according to its content. The 2 available "commands" in this workflow are: registerUCSAlertingInterface (or registerUCSAlertingCallback) and updateAlertMessage.

UCS Alerting Interface

This workflow is in charge of notifying any previously registered UCSAlerting interface about alert-related events happening inside UCS. The supported events are: a new Alert Message is present in UCS, an Alert Message was modified inside UCS and an Alert Message was canceled inside UCS. Each of this events is represented in the new workflow as an input port.

Just like UCS Client Interface workflow, this new workflow notifies any previously registered UCSAlerting callback about an alert-related event that happened inside UCS.

New Processors

UCSUpdateAlertMessage

This processor is the most important processor in the entire Alerting Interface implementation. This processor receives an AlertMessage as its input, and generates a FlowFile containing 2 AlertMessages.
The incoming AlertMessage MUST have a MessageId that is known inside UCS. The original Alert Message is then retrieved and a diff is performed between the old and the new version of the message.

Important: this implementation will only diff the alertStatus and statusByReciever properties of the messages.

The way the statuses of an Alert Message are processed is this:
1.- If the alertStatus property of the new message is different than the alertStatus property of the original message, the property in the original message is updated.
2.- (Only executed if the previous step was not)The statusByReciever entries of the new message are analyzed and updated in the original message. If, after the property is updated, the following scenarios must be evaluated:

• if the message contains a statusByReciever entry for each of its recipients and the status of each of them is Acknowledged -> the alertStatus property of the message is updated to Acknowledged.
• if the message contains a statusByReciever entry for each of its recipients but the status of each of them are not the same -> the alertStatus property of the message is not updated.
• if the message does not contain a statusByReciever entry for each of its recipients -> the alertStatus property of the message is not updated.

If there is no error during the execution of this processor, the output of this processor is a flowfile containing a serialized version of both, the original and the updated message.

UCSRegisterUCSAlertingCallback

This processor is used to register a callback URL that is used to notify about UCSAlerting-related events to a client. The implementation of this processor is very similar to UCSRegisterUCSClientCallback. UCSControllerService must be enhanced to keep track of these callbacks.

UCSGetUCSAlertingCallbacks

Similar to UCSGetUCSClientCallbacks, this processor retrieves any previously registered UCSAlerting callback URL from UCSControllerService and generates a flowfile for each of them.