Table of Contents
List of Tables
The main Oreka components accessible by API are:
Table 2.1. OrkTrack (Web UI backend) API table
Table 2.2. OrkWeb (Web UI frontend) API table
Command | Description | Example |
---|---|---|
OrkWeb (Web UI front end) | ||
Remote login (or Single Sign-On) | Log in to OrkWeb by API | http://localhost:8080/orkweb/app?username=myname&password=mypwd&startdate=20120215_121500&enddate=now&userid=2&filterby=false&mainmenu=false |
Direct access to pages | On-Demand page | http://localhost:8080/orkweb/app?page=LiveMonitoring&service=page&ondemand=true&localparty=5001 |
Recording details page (by tag) | http://localhost:8080/orkweb/app?page=SegmentDetail&service=page&localparty=5001&tagtype=Monitored&tagtext=test2 |
Table 2.3. OrkAudio (audio recorder) API table
Table 2.4. OrkRfb (screen recorder) API table
Command | Description | Example |
---|---|---|
OrkRfb (screen recorder) | ||
Start screen recording | Initiate screen recording for a given orkuid | http://localhost:59170/command?type=startrfb&hostname=deskto001&port=5900&loginstring=5001&username=john&password=mypassword&orkuid=20090801_144451_ABC |
Pause screen recording | Pause screen recording for a given orkuid | http://localhost:59170/command?type=pauserfb&hostname=deskto001&port=5900&loginstring=5001&username=john&password=mypassword&orkuid=20090801_144451_ABC |
Stop screen recording | Stop screen recording for a given orkuid | http://localhost:59170/command?type=stoprfb&hostname=deskto001&port=5900&loginstring=5001&username=john&password=mypassword&orkuid=20090801_144451_ABC |
It is always better to use the API commands to OrkTrack rather than directly to the recorders, whereever possible. OrkTrack has built-in knowledge to identify which recorder a localparty or a recording ID (orkuid) belongs to, and will correctly play the proxy between the API consumer and producer.
This approach confers several advantages:
Table of Contents
This section provides details on each API command (expected parameters, type of response, ...)
The response is as follows:
class=livestatusresponse success=true returncode=NO_ERROR comment= userstatuses=inactive--NEITHER--68,localhost--59120!5001—5145551234--NEITHER--14--test1--IN--both--REC
The field of interest is userstatuses. It lists a series of statuses for the different users/local parties that are being inquired, comma-separated. In the example above, the assumption is that 2 local parties were being inquired for their statuses: 5000 and 5001. Below is an explanation of the different fields in the response.
Format: inactive--status--elapsed--diskSpaceUsedInKb
Where:
Example: inactive--NEITHER--68-3122
Format: hostname--tcpport!localparty--remoteparty--status--elapsed--orkuid--direction--side--paused--tags--diskSpaceUsedInKb
Where:
Example: localhost--59120!5001—5145551234--NEITHER--14--20091026_000347_HRT--IN--both--REC--ClientID-12345;Comment-rude to caller--3122
This command adds or updates a user into the OrkWeb database. The main key is the loginstring. If the login string exists, all data around it is updated. Otherwise, the user and login string are added. When an update occurs, only parameters with explicit values specified in the API command are updated in the database, all others remaining intact. The groupname and securitygroupname parameters allow association of the user to a logical and/or a security group.
* Semi-optional parameters may be required to complement the mandatory ones: either firstname and lastname or one of the groupname or securitygroupname pair should must be present.
Successful response example:
class=userresponse success=true comment= returncode=NO_ERROR
Unsuccessful response example:
class=userresponse success=false comment=Error:%sERROR_SAVING_USER returncode=ERROR_SAVING_USER
This command adds a login string to an existing user with at least one other login string. The main key is the findloginstring. The user associated to findloginstring will have a newloginstring associated to it.
Successful response example:
class=userresponse success=true comment= returncode=NO_ERROR
Unsuccessful response example:
class=userresponse success=false comment=Error:%sERROR_NO_USER_FOUND_FOR_LOGINSTRING returncode=ERROR_NO_USER_FOUND_FOR_LOGINSTRING
This command deletes a non-security group specified by its name. It only succeeds if the group name exists as a non-security group, and does not have duplicates.
Successful response example:
class=groupresponse success=true comment= returncode=NO_ERROR
Unsuccessful response example:
class=groupresponse success=false comment=Error:%sERROR_NO_USER_FOUND_FOR_LOGINSTRING returncode=ERROR_NO_USER_FOUND_FOR_LOGINSTRING
Login usage examples:
Logout usage examples:
http://orktrack-server:8080/orktrack/command?cmd=agentstate&state=logout&agent=5000&device=2000
http://orktrack-server:8080/orktrack/command?cmd=agentstate&state=logout&device=2000
http://orktrack-server:8080/orktrack/command?cmd=agentstate&state=logout&workstation=HomePC
Notes:
This API call is different than a standard API call in the sense that it opens a socket for an indefinite period of time. As long as the socket is open, the client gets live call lifecycle events as they happen in an easily parseable key-value format until the client tears down the socket. The server never attempts to tear down the socket. Fields values of the reported events are escaped using standard URL escaping rules .
Possible event types:
Example usage:
http://orkaudio-server:59150/command?type=streamevents
Example output:
type=tape&recid=20140127_114145_AAAB&stage=start&captureport=AAAB×tamp=1390840905&filename=2014%2F01%2F27%2F11%2F20140127_114145_AAAB&localparty=7037759393&localentrypoint=&remoteparty=8777639393&direction=out&duration=0&service=orkaudio-donkey&localip=76.10.215.231&remoteip=10.36.60.100&nativecallid=201488103_17918490@76.10.215.231&tags=&ondemand=false&side=both&hostname=donkey& type=addtag&localparty=&orkuid=20140127_114145_AAAB&tagtype=dtmfdigit&tagtext=0&offsetmsec=20006& type=addtag&localparty=&orkuid=20140127_114145_AAAB&tagtype=dtmfdigit&tagtext=0&offsetmsec=27008& type=tape&recid=20140127_114215_AAAC&stage=start&captureport=AAAC×tamp=1390840935&filename=2014%2F01%2F27%2F11%2F20140127_114215_AAAC&localparty=2013636464&localentrypoint=&remoteparty=8772096464&direction=out&duration=0&service=orkaudio-donkey&localip=10.36.60.100&remoteip=76.10.193.169&nativecallid=010B07DD-1430-2152-1C18-00000005@10.36.60.100&tags=&ondemand=false&side=both&hostname=donkey& type=tape&recid=20140127_114145_AAAB&stage=stop&captureport=AAAB×tamp=1390840905&filename=2014%2F01%2F27%2F11%2F20140127_114145_AAAB.wav&localparty=7037759393&localentrypoint=&remoteparty=8777639393&direction=out&duration=66&service=orkaudio-donkey&localip=76.10.215.231&remoteip=10.36.60.100&nativecallid=201488103_17918490@76.10.215.231&tags=&ondemand=false&side=both&hostname=donkey& type=tape&recid=20140127_114215_AAAC&stage=stop&captureport=AAAC×tamp=1390840935&filename=2014%2F01%2F27%2F11%2F20140127_114215_AAAC.wav&localparty=2013636464&localentrypoint=&remoteparty=8772096464&direction=out&duration=36&service=orkaudio-donkey&localip=10.36.60.100&remoteip=76.10.193.169&nativecallid=010B07DD-1430-2152-1C18-00000005@10.36.60.100&tags=&ondemand=false&side=both&hostname=donkey& type=tape&recid=20140127_114145_AAAB&stage=ready&captureport=AAAB×tamp=1390840905&filename=2014%2F01%2F27%2F11%2F20140127_114145_AAAB.wav&localparty=7037759393&localentrypoint=&remoteparty=8777639393&direction=out&duration=66&service=orkaudio-donkey&localip=76.10.215.231&remoteip=10.36.60.100&nativecallid=201488103_17918490@76.10.215.231&tags=&ondemand=false&side=both&hostname=donkey&
This command streams the audio data in real-time (e.g. Live Monitoring). The audio stream is 8 KHz, 16 bits per sample PCM audio data (128 Kbit/s).
For testing or troubleshooting, it's possible to redirect the resulting binary stream to a file and then import it in audio editor such as Audacity by using the raw import feature (file/import/raw data, pick the file, select signed 16 bit PCM, Little-endian, 1 channel if mono, 2 channels if stereo, 8000 Hz sample rate). Getting the raw binary date into a file can be done on the command-line like this:
wget "http://orkaudio-server:59120/?type=stream&localparty=5002"
For production systems however, it is safer to use the "recid" returned by the streamevents API command, so that if the given extension handles several calls concurrently or close to each other, there is a guarantee that the right call is actually streamed, e.g.
wget "http://orkaudio-server:59120/?type=stream&recid=20081113_031704_MNP"
When doing voice analytics, it might be a better idea to stream in stereo, i.e. have the audio for each side of the call be streamed in a separate audio channel. This typically helps achieving better results. A pre-requisite for this is to configure orkaudio for stereo recording. If already the case, then here is how to get a stereo stream:
wget "http://orkaudio-server:59120/?type=stream&recid=20081113_031704_MNP&stereo=true"
The resulting stream will be 16 bit samples, 256 Kbit/s, interlaced like in a stereo wav file. I.e. one sample for the left channel, one sample for the right channel, one sample for the left channel and so on.
The importtape API command allows you to import recordings made by another recording system. It can be useful compared to the standard tape message API especially when the external recordings need to be encrypted or converted to an audio format that is accepted by Oreka.
Here are the parameters details:
To trigger the importtape command to convert the media file using an external tool using CLI (e.g. convert mp3 audio into wav format), you would need to modify the config.xml as follows:
<TapeProcessors>BatchProcessing, CommandProcessing, Reporting</TapeProcessors> <CommandProcessingCommand>ffmpeg -i [IN] -acodec libgsm_ms -ab 13000 [OUT]</CommandProcessingCommand>
The CommandProcessingCommand must be added under the top node in that file and may be modified as needed. The [IN] and [OUT] representing the input and output files must appear literally (no need to specify filenames).
This API allows you to load a new orkaudio license WITHOUT restarting orkaudio. It assumes that you have applied the new valid orkaudio license file, license.txt, to the orkaudio installation folder (typically /etc/orkaudio on Linux, C:\Program Files\OrkAudio in Windows).
Here are some response examples for both success and failure:
<response> <success>true</success> <comment> License info: company name:abcd valid:true valid from:Tue 2016-01-05 00:00:00 EST valid to:Sat 2016-01-30 00:00:00 EST </comment> </response> <response> <success>false</success> <comment> License info: company name: valid:false valid from:Wed 1969-12-31 19:00:00 EST valid to:Wed 1969-12-31 19:00:00 EST </comment> </response>