This guide will help you test and implement a Command API that will allow an Alert automation to occur from a 3rd party emergency notification system. To know if your provider is compatible with our API, please check the list on our Command software page. For this document we will ensure that you can test and confirm the function of the API through Postman. Once this has been successful, please follow your emergency alert provider's documentation for specifics on how to use the API.

Before you start, please have the following available:

• The latest .JSON file script for copy/paste: Command API v5

• Alert image posted to a public URL (example: http://www.getcleartouch.com/media/CT24_Command-API-Test-Graphic-m3840-x-2160-px-1.png)

• Alert audio posted to a public URL (example: http://www.getcleartouch.com/media/EmergencyBroadcastSystem_BW.12117.wav)

• Text editor software

• Familiarity with Postman: Postman Documentation

• Command Organization Code and Device Groups setup correctly

Steps for Preparation

1. Open a text document and record the Command Organization Code

2. Upload the Alert image to a public URL

3. Upload the Audio file to a public URL

4. Copy/paste the URL(s) into a text document

5. Download the image and import it into an MD5 hash utility. We use this: https://emn178.github.io/online-tools/md5_checksum.html

6. Download the audio file and import it into an MD5 hash utility.

7. Copy/paste the hash for each image and each audio file into a text document

8. Import the .JSON file into Postman (below is a description of the purpose for each POST or GET request)

Send Alert to a Device Group

List Groups

1. Select “List Groups”

2. In the GET field replace {your school code} with your Command Organization Code.

3. Send the GET request

4. The Response field will generate a list of all the Groups with the “id” also known as “groudIds”. In the example below, the groups are listed and I can copy/paste the “id” of the “API Test” group.

Send the Image Alert to the Group

1. Select “Send Alert With Groups”

2. Enter the following (already gathered) information

1. “code” = Command Organization Code

2. “groupIds” = “id” from List Groups GET request

3. “url” = public URL of Alert image

4. “md5” = MD5 hash generated by the utility

3. Select “Send” to send the Alert to the specified Group

1. Multiple groupIds can be entered.

Add an Audio Alert with the Image and send it to the Group

1. Select “Send Image and Audio Alert Device Groups”

2. Enter the following (already gathered) information

1. “code” = Command Organization Code

2. “groupIds” = “id” from List Groups GET request

3. “url” = public URL of Alert image

4. “md5” = MD5 hash generated by the utility

5. “audioUrl” = public URL of Alert Audio file

6. “audioMd5” = MD5 hash generated by the utility

3. Select “Send” to send the Alert to the specified Group

1. Multiple groupIds can be entered

=======

Send Alert to Group with Token Header

Obtain the Token

In this case, we want to generate a Header for the payload so the request is secure and unique to each Alert. To accomplish this it is necessary to create a unique token by using a GET request. The following steps need to be taken after the Alert send has been tested and verified.

1. Select All and Copy the “Send Alert with Groups” script into a text editor

2. In the GET field replace {your school code} with your Command Organization Code.

3. Paste the Copied script into the Body field

4. Select “Send”

5. In the Body of the Response, Copy the “data” text as in the example below and paste it into a text editor

Send the Alert with a Token

• Select the POST “Send Alert With URL And Token” and view the “Headers”

• Paste the Token in the Value field on the “x-open-token” row

• Note: the x-open-app-key and the x-open-token will be entered into software that passes the payload with a Header instead of a Pre-Request Script.

• Select the Body tab and copy/paste your original script into the field (example image below)

• Select Send to confirm it is successful.

Cancel an Alert with a Token

In this example, we will cancel the alert to a specific group. As with the Alert function, this can be specified to a Device Group or Device Groups. This is just a screenshot of the example payload used for guidance.

Obtain the Token

1. Select “Get Token for Cancel Alert” and enter the Organization Code in the GET request and in the Body of the text where it states “your school code”

2. Select “Send” and copy/paste the “data” text into a text editor (example image)

Cancel the Alert

1. Select “Use the Token to Cancel and Alert”

2. Select Headers and Paste the Token in the Value field on the “x-open-token” row.

3. Select Body and enter the Command Organization Code in the “your school code” section

4. Enter the “groupIds” to designate the displays where the alert should be canceled.

1. Select “Send” to Cancel the Alert