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 teamName,

  Notification message,

  Recipient[ ] distribution,

  long delay,

  string customEscalationType,

  PersonalEscalationStep[ ] personalEscalationSteps

) throws PermissionDeniedException, invalidArgumentException;

where:

• sender is the notification sender's user name.
• password is the notification sender's password.
• teamName 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.
• customEscalationType identifies the custom type of escalation.
• personalEscalationSteps tracks the information relevant to a personal escalation. A personal escalation is an ordered list of personal escalation steps, each of which refers to a device and has a related time-out.

Notification Class

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

Syntax for the 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;

boolean allowRecipientData;

}

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)

• The default value is false.
• When true, AlertFind automatically transfers recipients to the specified conference call.

• allowRecipientData (optional)

• The 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 cancelNotification object cancels an in-progress notification.

Syntax for the cancelNotification object is:

boolean cancelNotification (

    String username,

    String password,

    long notificationId

) throws InvalidNotificationException, PermissionDeniedException, InvalidArgumentException;

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 canceled. This value is set when the API initiates the notification.

Query the Status of a Notification

The queryNotificationStatus 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, InvalidArgumentException;

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 canceled.
• 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 responded 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, InvalidArgumentException

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;

    string 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 below.
• 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.

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 canceled
7	User contacted, but no response received (for example, “Left voice mail message”)
8	User responded

Send a Notification Using a Scenario (deprecated)

The sendScenario object sends a notification using a pre-created scenario. The sender of the notification must have permission to send both notifications and scenarios to the team.

Syntax of the sendScenario object is:

long sendScenario(

    String sender,

    String password,

    String teamName,

    String scenarioName,

    long delay

) throws RemoteException, PermissionDeniedException, InvalidArgumentException;

where:

• sender is the sender's user name. It returns a token that identifies this incident that can be used to query the message status.
• password is the sender's password.
• scenarioName is the name of the scenario to be sent.
• delay is the period of time in minutes to delay before sending the notification.