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 document 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 Recordings

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 document returns 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"
   ]
}

Note

Custom fields that are not prefixed by “call.” or those that show up in the custom fields page in webconfig (not part of the call table) are requred to be uppercase when included in the query.

5.3. 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.4. Example Bash Script

This example script queries the system for a recording in progress on channel 1. It then uses the callguid to set the User ID field to Taylor Smith for that record.

#!/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/