5. Interfacing to NexLog’s REST API

5.1. Authentication

Authentication (username and password) information is passed via POST form data

POST /client/apps/login/

Form Parameters

• location – localhost

• username – user’s username

• password – user’s password

Example:

POST /client/apps/login/ HTTP/1.1
Host: 192.168.1.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
X-Requested-With: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: */*

location=localhost&username=Eventide&password=12345

5.1.1. Successful Authentication Response

The JSON object contains sessionKey which indicates a successful login. The session key does not need to be saved but the cookie information in the Set-Cookie HTTP header does need to be a part of future communications.

Example:

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate
Set-Cookie: eventide_soap_session=ZP1zlRUwExHcl5Wc; Path=/
Set-Cookie: eventide_soap_user=Eventide; Path=/
Content-type: text/html

{
   "username":"Eventide",
   "license":{
      "MP3":false,
      "SpeechToText":false,
      "hasATCMode":false,
      "hasNAB":true,
      "hasQuarantine":false,
      "hasRapidSOS":false,
      "packagedIncidentExport":false
   },
   "location":"localhost",
   "loginRc":-1,
   "password_expire_days":-1,
   "result":"success",
   "security":{
      "admin":"true",
      "system_security":null,
      "user_groups":{}
   },
   "sessionkey":"iOiw2LJyvggt7Sr8",
   "tos":""
}

5.1.2. Failed Authentication Response

A failed login is indicated by populated error and errorDetail fields

Example:

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate
Content-type: text/html

{
   "loginRc":-1,
   "password_expire_days":-1,
   "location":"localhost",
   "errorDetail":"Authentication failure",
   "error":"AUTH_FAULT"
}

If the session has timed out or an operation is being performed when the login has not been established then the JSON object will look as follows

Example:

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate
Content-type: text/html

{
   "isSSO":"0",
   "errorDetail":"Not logged in",
   "error":"NO_SESSION_FAULT"
}

5.2. Retrieving Recording Data

This method queries the system for records.

GET /apps/rest/call.json

Query Parameters

• type (string) – stackable return type (json, metadata, array)

• timezone (string) – timezone for the start and end time, default UTC

• columns (string) – comma separated list of data to return for each record, also uses call.X parameters below

• call.channelid (int) – channel number to return records for

• call.datastatus (char) – current state of the record (c, p)

• call.callguid (string) – unique id of the record

• call.calldirection (string) – inbound or outbound direction (i, o)

• call.duration (int) – length or the record in seconds

• call.starttime_timestamp (timestamp) – record’s start time

• call.stoptime_timestamp (timestamp) – record’s end time

• call.sourceid (int) – serial number of the record’s originating system

• call.isarchived (boolean) – if the record has been sent to an archive

Example Request:

The following example retrieves the callguid for the call in progress (call.datastatus=p) on channel 1 (call.channelid)

GET /client/apps/rest/call.json?type=json,metadata,array&timezone=America/New_York&columns=call.channelname,call.callguid&call.channelid=1&call.datastatus=p HTTP/1.1
Host: 192.168.1.1
Connection: keep-alive
Cache-Control: no-cache
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9
Cookie: eventide_soap_user=Eventide; eventide_soap_user_192.168.1.1=Eventide; eventide_soap_session=CxaxD4SjxgESH44J; eventide_soap_session_192.168.1.1=6xfRiDZmXz43fzN2

Example Response:

The returned JSON object contains the callguid in the rows parameter

HTTP/1.1 200 OK
Content-Type: application/json

{
   "count":1,
   "rows":[
      [
         "Channel One",
         "0XvGC4DKwSeOQv1m"
      ]
   ],
   "timestamp":1010181746,
   "rownumber":0,
   "offset":0,
   "total":1,
   "columns":[
      "channelname",
      "callguid"
   ]
}

5.3. Retrieving Data Based on Custom Fields

This method queries the system for records based on data in a Custom Field. All of the call.X parameters above can be used here as well.

GET /apps/rest/call.json

Query Parameters

• type (string) – stackable return type (json, metadata, array)

• timezone (string) – timezone for the start and end time, default UTC

• columns (string) – comma separated list of data to return for each record using call.X parameters above and userdefinedcallmetadata.X which will vary from system to system

• userdefinedcallmetadata.CAD_INCIDENT_ID (string) – a custom field with CAD data relating to the calls (make sure Custom Field names are in all caps)

Example Request:

The following example retrieves the start time (call.starttime_timestamp) and duration (call.duration) for a call with Custom Field CAD_INCIDENT_ID equal to QAZWSX

GET /client/apps/rest/call.json?type=json,metadata,array&timezone=America/New_York&columns=call.starttime_timestamp,call.duration&userdefinedcallmetadata.CAD_INCIDENT_ID=QAZWSX HTTP/1.1
Host: 192.168.1.1
Connection: keep-alive
Cache-Control: no-cache
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9
Cookie: eventide_soap_user=Eventide; eventide_soap_user_192.168.1.1=Eventide; eventide_soap_session=mZoFvzdFqa6NIe8O; eventide_soap_session_192.168.1.1=ei2zJufMmiK3OqXr

Example Response:

The returned JSON object contains the start time and duration in the rows parameter

HTTP/1.1 200 OK
Content-Type: application/json

{
   "count": 1,
   "rows": [
      [
        1706591167732,
        301
      ]
   ],
   "timestamp": 1107124117,
   "rownumber": 0,
   "offset": 0,
   "total": 1,
   "columns": [
      "starttime_timestamp",
      "duration"
   ]
}

Note

Custom Fields that are not prefixed by “call.” or those that show up in the Custom Fields page in the Configuration Manager (not part of the call table) are required to be uppercase when included in the query.

5.4. Associating Metadata to a Record

POST /client/apps/soap/

Form Parameters

• location – localhost **

• method – action to take against record setCallMetadata **

• channelid – channel number that the record is from

• callguid – unique record id to set metadata for **

• keys – array of metadata fieldnames to set **

• values – array of values corresponding to the keys **

** required

Example Request:

The following example sets the user_id custom field associated with call GUID HfE0YV13RO3rVVwv. The field value is set to Taylor Smith.

POST /client/apps/soap/ HTTP/1.1
Host: 192.168.1.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
X-Requested-With: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: */*

location=localhost&method=setCallMetadata&callguid=HfE0YV13RO3rVVwv&
keys=["user_id"]&values=["Taylor%20Smith"]

Example Response:

If the operation is successful the server will return

HTTP/1.1 200 OK
Content-type: application/json

{
   "result": true
}

5.5. Adding Annotations to a Record

POST /client/apps/soap/

Form Parameters

• location – localhost **

• method – action to take against record setCallMetadata **

• callguid – unique record id to set metadata for **

• keys – array of metadata fieldnames to set **

• values – array of values corresponding to the keys **

** required

Example Request:

The following example adds to, but does not overwrite, the annotations custom field associated with call GUID HfE0YV13RO3rVVwv. The annotation value is set to Agent properly greeted caller. The annotation time is a UNIX epoch timestamp with milliseconds and a value of 1706629349628 which equates to January 30, 2024 15:42:29.628 UTC. The annotation type is set to GOOD. Other annotation types can be seen in the Configuration Manager in Recording → Custom Fields, select ANNOTATIONS and click Edit Field.

POST /client/apps/soap/ HTTP/1.1
Host: 192.168.1.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
X-Requested-With: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Accept: */*

location=localhost&method=setCallMetadata&callguid=HfE0YV13RO3rVVwv&
keys='["%2BANNOTATIONS","ANNOTATION_TIME","ANNOTATION_TYPE"]'&
values='["Agent properly greeted caller","1706629349628","GOOD"]'

Example Response:

If the operation is successful the server will return

HTTP/1.1 200 OK
Content-type: application/json

{
   "result": true
}

5.6. Example Bash Script

This example script queries the system for a recording in progress on channel 1. It then uses the callguid and channelid to set the User ID field to Taylor Smith for that record. Lastly, it uses the callguid and channelid to add an annotation to the annotations custom field and sets the annotation type to GOOD which will display in MediaWorks DX as a green circle with a checkmark.

Note

The key used for adding annotations is +ANNOTATIONS but the example below uses the URL escaped %2B instead of + to make sure that wget doesn’t treat the + as an escaped space.

#!/bin/bash
NLHOST=192.168.22.98
USERNAME=Eventide
PASSWORD=12345
CHANNELID=1
LOGFILE=logfile.txt
COOKIES=cookies.txt

# Authenticate
wget -a ${LOGFILE} --save-cookies ${COOKIES} --keep-session-cookies --post-data location=localhost\&username=${USERNAME}\&password=${PASSWORD} -O auth.json http://${NLHOST}/client/apps/login/

# Get the guid of the call currently in progress
wget -a ${LOGFILE} --load-cookies ${COOKIES} --keep-session-cookies -O query.json "http://${NLHOST}/client/apps/rest/call.json?type=json%2Cmetadata%2Carray&timezone=America%2FNew_York&columns=call.callguid&call.channelid=${CHANNELID}&call.datastatus=p"

# extract call guid from JSON
queryraw=`cat query.json`
CALLGUID=`echo "{"${queryraw#*{} | jq -r '.rows[0][]'`

# use channelid and callguid to set user_id
wget -a ${LOGFILE} --load-cookies ${COOKIES} --keep-session-cookies --post-data location=localhost\&method=setCallMetadata\&channelid=${CHANNELID}\&callguid=${CALLGUID}\&keys='["user_id"]'\&values='["Taylor%20Smith"]' -O setMetadata.json http://${NLHOST}/client/apps/soap/

# use channelid and callguid to add an annotation at annotation_time and pinned with annotation_type GOOD
wget -a ${LOGFILE} --load-cookies ${COOKIES} --keep-session-cookies --post-data location=localhost\&method=setCallMetadata\&channelid=${CHANNELID}\&callguid=${CALLGUID}\&keys='["%2BANNOTATIONS","ANNOTATION_TIME","ANNOTATION_TYPE"]'\&values='["Agent properly greeted caller","1706629349628","GOOD"]' -O setMetadata2.json http://${NLHOST}/client/apps/soap/