Cisco Finesse - Redbox Call Suppression Gadget - Sequence Diagrams

These are the sequence diagrams between the Finesse Server and the recorder. All REST requests are sent via Finesse Server using the MakeRequest() function from the Gadgets API

Login to the Redbox Web Service API with the username and password (set as HTTP headers) and retrieve an authorization Token. The authToken header is then used (sent in the HTTP Header) for all other requests to the Web Server API.
Use the Devices List API request
- Search list of all Device IDs which match the agent's extension number - and set in DeviceId Array
- This means that even if there are multiple devices with same extension number - call suppression will still work (by requesting to suppress each and every device ID which matches the agent's extension number)
Set keep-alive timer countdown to activate keep-alive (and repeat!)
Send Start / Stop Suppression request for each of the Device IDs in the DeviceId Array
Send logout Request when agent logs out of Finesse

  Finesse Server->Redbox: HTTP POST - /api/v1/sessions/login [username/password set in headers]
  Redbox->Finesse Server: 200 OK - Body: {"authToken": "b6b14951-a7db-4e2a-895b-c6bf96ecbe6a"}
  Note left of Finesse Server: Login

</sequencediagram>

Hide Login button
Set Keepalive Counter to '0'
Run deviceList() Function (i.e. Get Device List)

Display Login Button
Display & Log Server Response
If we got valid JSON response from the Server (with some error details) - display this info otherwise state a general “Server Error”

POST /api/v1/sessions/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
password: xkzdBbQSCUBrwx8W
requestId: 3a59c4cc-617f-4846-9ff7-1e9f204b61a3
username: redboxapi
X-Forwarded-For: 10.123.123.20
X-shindig-dos: on
Content-Length: 0
Host: redbox1.mydomain.com:1480
Connection: Keep-Alive
User-Agent: Apache Shindig
Accept-Encoding: gzip, deflate

HTTP/1.1 200 OK
Content-Length: 52
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 10 Mar 2021 12:14:37 GMT

{"authToken":"fe9f3f8f-fa71-45ef-aa2b-98c6f9dbfcc0"}

  Finesse->Redbox: HTTP GET - /api/v1/config/devices [authToken set in headers]
  Redbox->Finesse: 200 OK - Body: (see below)
  Note left of Finesse: Device List

</sequencediagram>

{
    "devices": [
        {
            "channelName": "Alice",
            "deviceID": 2,
            "extension": "12021 (csfAlice)"
        },
        {
            "channelName": "Bob Bobster",
            "deviceID": 1,
            "extension": "12022 (SEP38ED1855072B)"
        },
        {
            "channelName": "Bob Bobster",
            "deviceID": 4,
            "extension": "12022 (ipcGerry)"
        },
        {
            "channelName": "Danny",
            "deviceID": 3,
            "extension": "12026 (SEP38ED1855072B)"
        }
    ]
}

Loop through the device list searching for your extension number.
If Device Found set _connected = true;
Each time you find your extension number (multiple device IDs for a single extension number could exist) push the Device ID to an Array -
```
_myDeviceId.push(device.deviceID)
```
If a Device ID is NOT found - display an error
Otherwise set the keep-alive countdown

Display Login Button
Display & Log Server Response
If we got valid JSON response from the Server (with some error details) - display this info otherwise state a general “Server Error”

GET /api/v1/config/devices?nocache=1615378477047 HTTP/1.1
authToken: fe9f3f8f-fa71-45ef-aa2b-98c6f9dbfcc0
requestId: 9a917dd8-a080-4aeb-acac-fb911c6d0d2e
X-Forwarded-For: 10.123.123.20
X-shindig-dos: on
Host: redbox1.mydomain.com:1480
Connection: Keep-Alive
User-Agent: Apache Shindig
Accept-Encoding: gzip, deflate

HTTP/1.1 200 OK
Content-Length: 2361
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 10 Mar 2021 12:14:37 GMT

{
    "devices": [
        {
            "channelName": "Alice",
            "deviceID": 2,
            "extension": "12021 (csfAlice)"
        },
        {
            "channelName": "Bob Bobster",
            "deviceID": 1,
            "extension": "12022 (SEP38ED1855072B)"
        },
        {
            "channelName": "Bob Bobster",
            "deviceID": 4,
            "extension": "12022 (ipcGerry)"
        },
        {
            "channelName": "Danny",
            "deviceID": 3,
            "extension": "12026 (SEP38ED1855072B)"
        }
    ]
}

  Finesse->Redbox: HTTP PUT /api/v1/sessions/keepAlive[authToken set in headers]
  Redbox->Finesse: 200 OK - Body: {}
  Note left of Finesse: Keepalive

</sequencediagram>

Note:
The keepAlive request is present to avoid sessions timing out which by default will happen after 5 minutes of inactivity. This is provided to allow a good response time to suppression requests by not needing to re-establish a session should it expire before other commands can be triggered. Note that an HTTP return code of 401 with extra information of the token being invalid can still be sent in response to any request (excluding login/logout) due to external factors and therefore should be handled appropriately. This Finesse Gadget keepalive timer is set by default to 150 seconds. Which is 50% of the session timeout of 5 minutes - as detailed above.

Set keepalive count to '0'
set countdown to keepalive again

setTimeout(function () {
            _keepalive();
        }, _keepaliveInterval);
    }

Add '1' to keepalive counter
display login button
Display & Log Server Response to console logs
If error is 401 (unauthenticated) automatically login again (call the _login() function) otherwise
if counter is less than max keep-alive count - try again at next keep-alive interval
if max keepalive count has been reached - give up!

PUT /api/v1/sessions/keepAlive HTTP/1.1
authToken: 9dd00e7a-707d-41bd-82d5-793963831b34
requestId: 49a57510-074b-4ec6-a5b7-d77d9a9a3970
X-Forwarded-For: 10.123.123.20
X-shindig-dos: on
Content-Length: 0
Host: redbox1.mydomain.com:1480
Connection: Keep-Alive
User-Agent: Apache Shindig
Accept-Encoding: gzip, deflate

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 10 Mar 2021 11:41:49 GMT
{}

  Finesse->Redbox: HTTP POST /api/v1/suppression/start/device [{"deviceID": 202}]
  Redbox->Finesse: 200 OK - Body: {}
  Note left of Finesse: Start Suppression

</sequencediagram>

Send Start Suppression for the First Device ID in your DeviceID array (there could be more than one)

Check if we have looped through all the Device IDs in the Device ID Array.
If so display the success message on the screen for successfully Started Suppression
If not, run the Start Suppression Function again for the next DeviceID (_myDeviceIdCounter++ )

Update the connected state to false
Display server error on screen if available
If error was a 401 error attempt to login again - otherwise show the login button

POST /api/v1/suppression/start/device HTTP/1.1
authToken: 9dd00e7a-707d-41bd-82d5-793963831b34
Content-Type: application/json
requestId: 7bdaa408-04e8-47fc-b551-2f7120112c64
X-Forwarded-For: 10.123.123.20
X-shindig-dos: on
Content-Length: 17
Host: redbox1.mydomain.com:1480
Connection: Keep-Alive
User-Agent: Apache Shindig
Accept-Encoding: gzip, deflate

{"deviceID": 202}

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 10 Mar 2021 11:41:15 GMT
{}

  Finesse->Redbox: HTTP POST /api/v1/suppression/stop/device [{"deviceID": 202}]
  Redbox->Finesse: 200 OK - Body: {}
  Note left of Finesse: Stop Suppression

</sequencediagram>

Send Stop Suppression for the First Device ID in your DeviceID array (there could be more than one)

Check if we have looped through all the Device IDs in the Device ID Array.
If so display the success message on the screen for successfully Stopped Suppression
If not, run the Stop Suppression Function again for the next DeviceID (_myDeviceIdCounter++ )

Update the connected state to false
Display server error on screen if available
If error was a 401 error attempt to login again - otherwise show the login button

POST /api/v1/suppression/stop/device HTTP/1.1
authToken: 9dd00e7a-707d-41bd-82d5-793963831b34
Content-Type: application/json
requestId: 4caaa138-a07c-4228-a0e4-b202aaaadd59
X-Forwarded-For: 10.123.123.20
X-shindig-dos: on
Content-Length: 17
Host: redbox1.mydomain.com:1480
Connection: Keep-Alive
User-Agent: Apache Shindig
Accept-Encoding: gzip, deflate

{"deviceID": 202}

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 10 Mar 2021 12:13:19 GMT

{}

  Finesse->Redbox: HTTP POST /api/v1/sessions/logout
  Redbox->Finesse: 200 OK - Body: {}
  Note left of Finesse: Logout

</sequencediagram>

POST /api/v1/sessions/logout HTTP/1.1
Content-Type: application/xml
X-egain-session: d8a1d8fc-b82a-49b7-b4ab-76e1476ad19d
authToken: 9dd00e7a-707d-41bd-82d5-793963831b34
cache-control: no-cache
Accept: */*
Host: redbox1.mydomain.com:1480
accept-encoding: gzip, deflate
content-length: 201
Connection: keep-alive

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Wed, 10 Mar 2021 16:30:51 GMT

{}

Cisco Finesse - Redbox Call Suppression Gadget - Sequence Diagrams

High Level - How the Gadget Works

Success

Error

Example HTTP LOGIN Request

Device List

Example Response

Success (if (response.rc >= 200 && response.rc < 300 && handlers.success))

Error

Example HTTP Request

Keepalive

Success (if (response.rc >= 200 && response.rc < 300 && handlers.success))

Error

Example HTTP KeepAlive Request and Response

Start Suppression

Success

Error

Example HTTP Start Suppression

Stop Suppression

Success

Error

Example HTTP Stop Suppression

Logout

Example HTTP Logout Request