Question/Problem Description

Clarifying Information:

Notification API

APIs

There are two application programming interfaces (APIs), the notification API and the data management API. To use the APIs, this feature must be enabled in your company settings. This setting is controlled by Support.

To use the AlertFind APIs you must understand object-oriented programming and web services.

See  Data Management API  for more information.

Notification API

By using the AlertFind simple object access protocol (SOAP) API you can allow an external system to send predefined notifications. This is particularly useful if your organization uses monitoring systems that can send triggers to an external system.

The API mirrors UI-based processes relating to notifications, though it requires knowledge and understanding of the available objects and classes.

The SOAP API is described using the web service description language (WSDL). The WSDL file is available at your AlertFind data center and provides a standard description of the AlertFind notification service API. See "Web Services"  for more information about the WSDL file. Most programming languages understand the WSDL and can automatically build interfaces that invoke the AlertFind notification API. The WSDL file for AlertFind is located at:

https://BACKEND_URL/soap-api/notification?WSDL

where BACKEND_URL is your AlertFind URL.

SOAP API Requirements

You must provide a valid user name and password for an account that has permission to send, view, or cancel notifications and incidents. The specific permission or permissions required depends on the API function you use.

Send a Notification

The sendNotification object enables sending a notification to users by AlertFind administrators and team leaders with send notification permission.

Syntax for the sendNotification object is:

long sendNotification (

String sender,

String password,

String team,

Notification message

Recipient [ ] distribution

long delay

) throws PermissionDeniedException,

invalidArgumentException;

where:

• sender is the notification sender's user name.
• password  is the notification sender's password.
•   team is the AlertFind team with which this message is associated:

- If the value of team is null and the sender has send notification permission for only one team, AlertFind uses that team.

- If the value of team is null and the sender is an administrator, AlertFind uses the Global Team.

- If the user identified as the sender has permission to send to more than one team and this parameter is null, an error occurs.

• message  is the message to send.
• distribution identifies the notification recipient or recipients.
• delay  is the amount of time in milliseconds AlertFind waits between receipt of the notification trigger and sending the notification.
• long sendNotification is a 64-bit number.

Notification Class

The notification class used in the sendNotification object describes a message that the API can trigger.

Syntax for the send notification class is:

class Notification {

String subject;

String body;

boolean authenticationRequired;

String confCallNumber;

String confCallMeetingId;

boolean stopOnResponses

Response[ ] responses;
}

where:

• subject  is the subject of the notification (cannot be null).
• body is the text of the notification (cannot be null).
• authenticationRequired  is optional; the default is false. If the value is true, each notification recipient must enter a valid PIN to hear or read the notification.
• confCallNumber and confCallMettingID  (optional) provide information AlertFind needs when it connects the recipient to a conference call. If these properties are set:

- Notifications include conference call details.

- Responses where bridgeToConfCall  equals true  transfer recipient to the conference call.

• stopOnResponses  specifies whether AlertFind should stop notifying additional recipients after the limits set for all possible responses are met.
• responses  provides a list of possible responses. If null or empty, the notification provides recipients with the standard response of €œI confirm that I€™ve received this message.€�

Response Class

A Response class used in the Notification object provides available responses from which notification recipients can select.

Syntax for the Response object is:

class Response {

String description;

String abbreviation;

int maxRecipients;

boolean bridgeToConfCall;

}

where:

• description  is the text spoken for this notification (or included as message text if received as an email).
• abbreviation is the abbreviation used as a reference to this response both in the API and the UI.
• maxRecipients  (optional) is the maximum number of recipients allowed for this response.

- Default value is 0. When the value is 0, AlertFind contacts all identified recipients.

- When the number of responses received equals maxRecipients, AlertFind stops trying to deliver the notification to additional recipients.

• bridgeToConfCall (optional)

- Default value is false.

- When true, AlertFind automatically transfers recipients to the specified conference call.

Recipient Class

The Recipient class used in the sendNotification object identifies the recipients for a specified notification.

Syntax for the Recipient class is:

class Recipient {

String type;

String id;

long delayAfter

}

where:

• type  is the type of recipient. Possible values are:

- user  for a user name.

- group  for the name of a group.

- dist  for the name of a predefined distribution list (escalation group).

• id is the identification of the recipient. The meaning of this property varies with type.
• delayAfter  is the amount of time in milliseconds that AlertFind waits between recipients when it sends the notification. If the value of delayAfter is 0, AlertFind sends the notification to all recipients simultaneously.

Cancel a Notification

The Cancel object cancels an in-progress notification. Syntax for the Cancel object is:

boolean cancelNotification (

String username,

String password,

long notificationId

) throws InvalidNotificationException,

PermissionDeniedException;

where:

• sender  is the user name of the user who is initializing the cancellation.
• password  is the password of the user who is initializing the cancellation.
• notificationID  identifies the notification to be cancelled. This value is set when the API initiates the notification.

Query the Status of a Notification

The queryNotificationStatusSummary object searches for and returns summary information about a notification. The query results resemble the notification status information that appears on the Notifications page of the UI.

Syntax for the queryNotificationStatus object is:

NotificationStatusSummary queryNotificationStatusSummary(

String username,

String password,

long notificationId

) throws InvalidNotificationException,

PermissionDeniedException;

where:

• username  is the user name of the user performing the query.
• password is the user€™s password.
• notificationId  identities the notification for which status information is needed. This value is set when the API initiates the notification.

NotificationStatusSummary Class

The NotificationStatusSummary class used in the queryNotificationStatus object returns the status of a specified notification.

Syntax for the NotificationStatusSummary class is:

class NotificationStatusSummary {

String status;

ResponseCount[ ] responses;

}

where:

status  is the status of the notification. Possible statuses are:

- Manual €”Notification is waiting for manual execution.

- Pending €”Notification is pending.

- Scheduled €”Notification is scheduled.

- Cancelled €”The notification was cancelled.

- Scheduling €”Notification is being scheduled.

- Error €”Notification has an error.

- Executing €”Notification is executing.

- Complete €”Notification is completed.

- Notifications_Completed €”Notifications are completed.

- responses is a value array containing a breakdown of counts by response. Additionally, the final array element represents the number of contacts who have not responded in any way. In situations where one or more of the response options has been defined with a response limit, then there is an additional array entry preceding the final one and it holds the number of contact attempts terminated because their limit was reached.

For example, if the possible responses are delayed and confirmed and no responses limits were established, then:

response[0] shows the number of contacts whose responses were delayed.

response[1] shows the number of contacts who responded. confirmed.

response[2  ]shows the number of contacts who have not responded in any way.

Alternately, if the possible responses are delayed and confirmed and a responses limits was specified, then:

response[0] shows the number of contacts whose responses were delayed.

response[1] shows the number of contacts who responded confirmed.

response[2] shows the number of contact attempts have been terminated because the response limits were reached.

response[3] shows the number of contacts who have not responsed in any way.

ResponseCount Class

The ResponseCount class used in the queryNotificationStatus object is an array containing a breakdown of counts by response.

Syntax for the ResponseCount class is:

class ResponseCount {

String abbreviation;

int count;

}

where:

abbreviation is one of the following:

- The abbreviation corresponding to the selected response.

- Null indicates no abbreviation has been specified for this response or that an extra one or two summary responses occur at the end.

count is the number of recipients:

- Who selected the response specified by the abbreviation.

- Null is an integer.

Query the Status of a Notification Recipient

The queryRecipientStatus object retrieves recipient status. This information resembles the information displayed on the Recipients tab of the Notification Details page. This object returns the most complete status, but not necessarily the last activity, of the notification recipient. For example, if the user acknowledged the message using their Work Phone device, the latest activity is €œHung up,€� but the reported status is €œWork Phone: Confirmed€�.

Syntax for the queryRecipientStatus object is:

RecipientStatus[ ] queryRecipientStatus(

String username,

String password,

long notificationId

) Throws InvalidNotificationException,

PermissionDeniedException

 

where:

• sender is the user performing the query.
• password is the user€™s password.
• notificationID is the notification the object is to query.

RecipientStatus Class

The RecipientStatus class used in the queryRecipientStatus object provides information about the queried recipient.

Syntax of the RecipientStatus class is:

class RecipientStatus {

String name;

String username;

Date timestamp;

int StatusCode;

String statusMessage;

String response

}

where:

• name is the display name of the recipient.
• username is the recipient€™s user name. If the recipient has more than one user name, this user name cannot match the user name in the Recipients object for the sendNotification method (though both user names identify the same user).
• timestamp is the time stamp of the status event.
• statusCode is the internal status code for the event. See Table 16-1.
• statusMessage is the descriptive text associated with the status event.
• response contains the abbreviation corresponding to the recipient€™s response, if any, to the notification. If the recipient did not respond to the notification, the value returned for response is null.

Table 16-1 Internal Status Codes

Status Code	Meaning
0	Preparing to notify recipient.
3	Notification in progress (for example, €œdialing€�)
4	Error indicating delivery retry (for example, €œNumber busy€�)
5	Permanent error (for example, €œInvalid number€�)
6	Notification cancelled
7	User contacted, but no response received (for example, €œLeft voice mail message€�)
8	User responded