Contextualización de la propuesta didáctica

The SA-Announce web service (API) provides methods that can be used to perform operations such as activating or deactivating an emergency alert group or dispatching a text message. The methods are accessed via HTTP (standard or SOAP encapsulated) GET/POST to the SA-Announce web service.

To browse the available methods, open Internet Explorer on the application server and navigate to http://<SA- Announce-Server>/SA-Announce/API/SAAnnounceAPI.asmx. A list of available methods will be shown with descriptions. Clicking on one of the method names will display the methods full description page. This page allows the method to be tested and shows sample request and response formats.

Programmers can access the web service description language file at http://<SA-Announce-Server>/SA- Announce/API/SAAnnounceAPI.asmx?WSDL.

While the web service description page can only be accessed from the application server, the web service methods can be accessed from any authorized server. To configure authorized servers see Service Configuration Options, Servers authorized to use the SA-Announce API setting.

Methods with user name and password parameters only require the user name and password if the requesting server is not a server authorized to use the SA-Announce API.

Important: Most methods require a group-Id to activate the notification group. The group-Id can be found on the Create / Edit Groups page. The group-Id for the selected group will appear to the right of the Group Type drop down list.

The various methods are described in the following table:

API Method Description

Dispatch Methods _{Methods that activate notification group functionality.}

DispatchEmergencyAlert _{Invoke this method to activate or deactivate an emergency alert group.} Parameters -

id [int] - the group-Id of the emergency alert group to activate..

userName [string] - the SA-Announce user name of the requesting user. passw ord [string] - the SA-Announce passw ord for the requesting user. start [bool] - true to start the emergency, false to end it (for alert mode only). (optional) securityCode [string] - the group security code, if one exists.

DispatchEAOverride _{Invoke this method to activate or deactivate an emergency alert group with} overridden text.

Parameters -

id [int] - the group-Id of the emergency alert group to activate.

userName [string] - the SA-Announce user name of the requesting user. passw ord [string] - the SA-Announce passw ord for the requesting user. start [bool] - true to start the emergency, false to end it (for alert mode only). overrideText [string] - the new text to attach to the group.

(optional)securityCode [string] - the group security code, if one exists.

DispatchGroupStoredAudioMode _{Invoke this method to activate a normal group type in stored audio mode. In} this mode the group endpoints will play the specified audio file for a number of repeats and then end. This method does not support EA groups, use DispatchEmergencyAlert instead.

Parameters -

id [int] - the group-Id of the normal group to activate.

Web Service (API) 151

© 2015 Syn-Apps L.L.C.

text [string] - the text to send to endpoints (255 char max). repeatNumber [int] - the number of times to repeat the audio file. cancelButton [bool] - true to send a cancel button to IP phone endpoints. (optional)securityCode [string] - the group security code, if one exists. DispatchGroupStoredAudioModeByGrou

pName

Invoke this method to activate a normal group type in stored audio mode. In this mode the group endpoints will play the specified audio file for a number of repeats and then end. This method does not support EA groups, use DispatchEmergencyAlert instead.

Parameters -

group_name [string] - the group name of the normal group to activate. w avFile [string] - the name of the SA-Announce alert w av file. text [string] - the text to send to endpoints (255 char max). repeatNumber [int] - the number of times to repeat the audio file. cancelButton [bool] - true to send a cancel button to IP phone endpoints. (optional)securityCode [string] - the group security code, if one exists.

DispatchImageURL _{Invoke this method to send an image to the endpoints in a target group. A} text parameter is required for endpoints that do not support images. Parameters -

id [int] - the group-Id of the emergency alert group to activate. text [string] - the text to send to endpoints that do not support images. soundToPlay [string] - the TFTP sound to play upon delivery IE analog1.raw . imageURL [string] - the URL of the .png image to display in the message. userName [string] - the SA-Announce user name of the requesting user. passw ord [string] - the SA-Announce passw ord for the requesting user. DispatchTextMessage _{Invoke this method to send a text message to the endpoints in a target}

group. Images must be located in the SA-Announce\Images\ directory. Parameters -

id [int] - the group-Id of the emergency alert group to activate. text [string] - the text to send to endpoints that do not support images. soundToPlay [string] - the TFTP sound to play upon delivery IE analog1.raw . imageFileName [string] - the name of the image to display in the message. userName [string] - the SA-Announce user name of the requesting user. passw ord [string] - the SA-Announce passw ord for the requesting user. Inform ation Methods _{Methods that return SA-Announce configuration information.}

GetDeviceByDN _{Invoke this method to get a list of available IP phone devices with the given} directory number. Use % as a wildcard (this is a LIKE statement). Returned Parameters -

name [string] - the device name (IE SEP001122334455). ip [string] - the device IP address.

description [string] - the device description. display [string] - the line display (caller-Id).

dn [string] - the directory number attached to the device. xmlEnabled [bool] - true if the device is an XML enabled IP phone.

GetDeviceByUserName _{Invoke this method to get a list of available IP phone devices with the given} user name in the line display field (caller-Id). Use % as a wildcard (this is a LIKE statement).

Returned Parameters -

name [string] - the device name (IE SEP001122334455). ip [string] - the device IP address.

description [string] - the device description. display [string] - the line display (caller-Id).

dn [string] - the directory number attached to the device. xmlEnabled [bool] - true if the device is an XML enabled IP phone.

SA-Announce ShoreTel User Guide 152

© 2015 Syn-Apps L.L.C. GetEmergencyAlertGroups _{Invoke this method to get a listing of emergency alert groups.}

Returned Parameters -

name [string] - the group name. groupId [int] - the group-Id.

type [string] - the group type (EmergencyAlert). alertMode [bool] -true if this is an alert mode group. repeatMode [bool] - true if this is a repeat mode group.

GetGroupListing _{Invoke this method to get a list of groups the given user is allowed to} access.

Returned Parameters -

name [string] - the group name. groupId [int] - the group-Id.

type [string] - the group type (EmergencyAlert). alertMode [bool] -true if this is an alert mode group. repeatMode [bool] - true if this is a repeat mode group. securityCode [string] - the groups security code, if one exists. isActive [bool] - true if the group is currently active.

GetImageList _{Invoke this method to get a list of available image files (SA-Announce image} files are located in the SA-Announce/Images directory and must be .png). Returned Parameters -

name [string] - the image file name. url [string] - the HTTP URL of the image file. size [long] - the size of the image file in bytes.

GetSoundList _{Invoke this method to get a list of available audio alert files (SA-Announce} audio alert files are located in the SA-Announce/Broadcaster/AlertWav directory and must be encoded properly).

Returned Parameters -

name [string] - the w av file name. url [string] - the HTTP URL of the w av file. size [long] - the size of the w av file in bytes. End-Point Registration and Heart

Beat

Methods to register and keep-alive IP endpoints. RegisterDesktopClient _{Syn-Apps Desktop Client Register Method.} DesktopClientHeartBeat _{Syn-Apps Desktop Client Heart Beat Method.}

RegisterIpSpeaker _{Syn-Apps IP Speaker Register Method. See Syn-Apps IP Speaker Setup} for details.

IpSpeakerHeartBeat _{Syn-Apps IP Speaker Heart Beat Method.} Other Methods _{Methods not intended for public use}

There are a number of methods listed as not intended for public use, please refrain from using these unless directed by Syn-Apps support.