Eventra Java Recording API

5/17/2018 Eventra Java Recording API - slidepdf.com

http://slidepdf.com/reader/full/eventra-java-recording-api 1/29

Eventra

Java Recording

APIGuide

Updated - March 2009

Document Version 1.1



Eventra Java Recording API Guide v1.0

© Copyright Empathy Systems 2009. All rights reserved. CONTENTS

© Empathy Systems 2009



Eventra Java Recording API v1.0

© Empathy Systems 2009. All rights reserved Page 2 of 29 January 2009

IMPORTANT INFORMATION

Eventra Recording API

The information in this document is confidential and subject to changewithout notice.

This document has been produced by Empathy Systems (Empathy) with greatcare and attention to detail. Every effort has been made to ensure accuracyand fitness for purpose. However, please note the following:

• Empathy makes no representation or warranty with respect to thecontents of this document.

• Empathy disclaims any implied warranties of the merchandise or impliedfitness for any particular purpose.

• Empathy supplies this documentation as an act of goodwill. Under nocircumstances shall Empathy, or its employees, be responsible for anylosses, or consequential losses, incurred in connection with its contentsor use.

• Empathy reserves the right to revise this publication, or the productspecification, at any time without notification.

2009 Empathy Systems All rights reserved

Contact address:

Empathy Systems

Langebjergaenget 8ADK-4000 RoskildeDenmark



Eventra Java Recording API v1.0


"Building creative applications, delivering proven solutions"

Eventra is designed and developed by Empathy, one of the industry’s leadingsuppliers of voice and data technology solutions. It is part of a completeportfolio of CTI, call management and voice/data recording solutions,designed to help companies achieve their quality management goals, improvecustomer service and increase business efficiency.

Empathy places emphasis on delivering open, scaleable software solutionsthat integrate seamlessly with today’s enterprise Microsoft ® OperatingSystems and telecoms environments and has long-standing alliances with theworld’s leading switch manufacturers.

Empathy products are backed by a complete range of consultancy, bespokedevelopment and pre- and post-sales support services. Our developmentexpertise and the open, object-oriented nature of our products enable ourapplications to be customized to meet the exact requirements of our corporatecustomers and distribution partners.

Our customer base is testament to the quality and reliability of our productsand our support services. Our applications are as successful in the missioncritical command and control environment, as they are in fast moving Citydealing rooms or rapidly expanding call centres.

Please visit the Empathy web site at http://www.empathy-systems.com/ orcontact the marketing department on [email protected] forinformation on our range of products.





ContentsPage Number

INTRODUCTION ............................................................................................. 5

SYSTEM REQUIREMENTS ............................................................................ 5

NOTIFICATION EVENTS ................................................................................ 7

API FUNCTIONS ........................................................................................... 10

OPEN CONNECTION....................................................................................... 12

open ......................................................................................................... 12

CLOSE CONNECTION ..................................................................................... 13

close ........................................................................................................ 13

GET RECORDING EVENT ................................................................................ 14

getRecordingEvent .................................................................................. 14

START RECORDING ....................................................................................... 15

startRecording .......................................................................................... 15

STOP RECORDING ........................................................................................ 17

stopRecording .......................................................................................... 17

stopRecordingDiscard .............................................................................. 18

TAG CALL ..................................................................................................... 19

tagCall ...................................................................................................... 19

tagCurrentCall .......................................................................................... 20

tagFinishedCall ........................................................................................ 21

TRANSFER CALL............................................................................................ 22

callTransferred ......................................................................................... 22

PCIDSS ...................................................................................................... 23

muteCall ................................................................................................... 23

unMuteCall ............................................................................................... 24

pauseCall ................................................................................................. 25

restartCall................................................................................................. 26

APPENDIX A – EXAMPLE ............................................................................ 27





Introduction

This document describes the Eventra Java Recording API that allowsexternal applications to control recording through a Java Interface.

This API is made up of a number of Java classes which use JNI (Java NativeInterface) to call C++ language functions packaged in a DLL. This C++ DLLencapsulates all the Empathy framework communication and enablesrecording to be controlled by an external application with a few simple functioncalls.

This API is designed to be used through a Java based application; the C++DLL can be used direct if the calling application is C++ based. Another Guideis provided ‘Eventra Recording API Guide’ for this purpose.

System Requirements

At present this API is supported on Microsoft Windows XP and MicrosoftWindows 2003 Server.

The system must be running a TCP/IP protocol stack on its network interface.The system must also be able to communicate with all the relevant Eventracomponents; this requires any intervening network routers to be multicast-enabled.

In order to use the API the application must include the following files:

On the CLASSPATH:

java-recording-api.jar

Includes Java classes. which access the API using JNI.

On the application PATH:

JavaRecordingAPI.dll

Includes JNI enabled C++ class which accesses the C++ API.

ESapi.dll

Includes C++ functions which provide recording functionality viathe Eventra framework.

framework.cfg

Provides Configuration information that allows C++ API tocommunicate with Eventra Framework.

This file should contain as a minimum:

The location and port of the Eventra server, i.e.[Framework]

configDB address : 192.168.1.118

configDB port : 55000

CTI Provider section indicating which module to use, which should have a matching [nameComponent-Config] section onthe server-side framework.cfg (where name is the module





specified in the client framework.cfg), for each instance of theAPI that is to be run, it will specify which recorder/s it can talk to.

e.g.

(client-side)

[CTI Provider]module : CTIProvider1

(server-side)[CTI Provider1Component-Config]

noOfItems : 1

1: I_CONNECT, ALL, Recorder1

It is also recommended that the recorder is configured to sendevents to all clients.

e.g.

(server-side)[Recorder] send events to all = Y





Notification Events

Communication between the client application and Eventra are asynchronousand completion codes of commands etc. are sent to the client as notificationevents.

This API only supports the Recording Events returned by the Eventraframework.

All event-based classes reside in the packagecom.tisl.eventra.recordingapi.event





Recording events are represented by thecom.tisl.eventra.javarecordingapi.RecordingEvent class.

This class is used by the client to pass information to and from the

Framework.Each API method call will require different parameters to be set within thisclass and will also generate one or more Recording Events from theframework, each method’s requirements are described later.

There are more than one type of recording event, the type of recording eventcan be determined by using the getEvent() method on the

RecordingEvent class, this will return an int which can be checked against

the following constants defined in the RecordingAPI class:

// Recorder Events.......

RECORD_STOP_SHORT=0x00010000

RECORD_STOP_VOX=0x00010001

RECORD_STOP_DTMF=0x00010002

RECORD_STOP_CTI=0x00010003

RECORD_HALT=0x00010004

RECORD_SHUTDOWN=0x00010005

RECORD_START_VOX=0x00010006

RECORD_START_DTMF=0x00010007

RECORD_START_CTI=0x00010008

RECORD_WAIT_VOX=0x00010009

RECORD_WAIT_DTMF=0x0001000A

RECORD_WAIT_CTI=0x0001000B

RECORD_FAIL_BAD_NAME=0x0001100C

RECORD_NO_FREE_LICENCE=0x0001100D

RECORDING_PROTECTED=0x0001000E

RECORDING_UNPROTECTED=0x0001000F

RECORD_START_FAILED=0x00011010

RECORD_STOP_FAILED=0x00011011

RECORD_TRANSFER=0x00010013

RECORD_HELD=0x00010016

RECORD_UNHELD=0x00010017

RECORD_CONFER=0x00010014

RECORD_CONFER_DROP=0x00010015

RECORD_TAGG_SUCCESS=0x00010012

RECORD_TAGG_FAIL=0x00011012

RECORD_MUTED=0x00010018





RECORD_UNMUTED=0x00010019

RECORD_PAUSED=0x0001001A

RECORD_UNPAUSED=0x0001001B

RECORD_MUTE_FAILED=0x00010028

RECORD_UNMUTE_FAILED=0x00010029

RECORD_PAUSE_FAILED=0x0001002A

RECORD_UNPAUSE_FAILED=0x0001002B





API Functions

All API functions are defined as static methods withincom.tisl.eventra.recordingapi.RecordingAPI class.





All methods other than open, close and getRecordingEvent areAsynchronous (i.e. non-blocking).

For Asynchronous method calls, if no exception is thrown and the methodcompletes normally then this means that a request has been sent to Eventra itdoes not indicate that the request was successful.

Notification Events will be generated by the Eventra Framework which willconfirm the success/failure of requests made. It is the Client’s responsibility toretrieve the events and inspect them to identify the outcome.

The getRecordingEventmethod allows the client to retrieve the nextqueued event.

Eventra recording channels are identified by their trunk or extension number(depending on the recorder hardware configuration). This is the channelPBX_Ext value as displayed in the Eventra client channel configuration

screen. It is this value which must be passed in the relevant API calls to

identify the recording channel. If an API call is made for an invalid channel orfor a channel which is not accessible for any reason then aRECORD_FAIL_BAD_NAME type event will be generated for that channel.

Each API method is described in detail below:





Open Connection

open

Initializes the CTI connection to Eventra.public RecordingAPIHandle open(String clientName)

ParametersclientName String used to identify this client in logs etc.

ReturnsRecordingAPIHandle Handle for use in all other API calls.

ThrowsRecordingAPiException unexpected error thrown by API.

ConnectionFailedException connection to Eventra could not be made.

BadParameterException clientName not specified.

This must be the first call made to the Eventra Recording API.

This function will allocate and initialize the resources required to maintain aclient connection to Eventra. A network connection is also established at thispoint. Subsequent calls to the API should use the RecordingAPIHandle

returned by this method.

Note that this method is synchronous and will not return until all the necessaryconnections have been made.

No notification events will be generated as a result of this request.

Please Note.

Due to a limitation of the underlying C++ API, only one handle can be held atany one time per application, This handle should be retrieved by using thismethod when the application starts and released by using the close method(described below) when the application exits, any attempt to open anotherconnection within the same application instance may produce unexpectedresults.





Close Connection

close

Closes the CTI connection.public void close(RecordingAPIHandle handle)

Parametershandle Handle returned by previous call to open method.


BadHandleException Invalid handle (e.g. open not yet called, or

handle already closed).

BadParameterException handle not specified.

This method must be called when an application no longer requires theservices of the Eventra API connection. All other Eventra components will beinformed that the application has shut down.

Once this call has been made the handle is no longer valid and any furthercalls to the API will fail.

No notification events will be generated as a result of this request.





Get Recording Event

getRecordingEventpublic RecordingEvent getRecordingEvent(RecordingAPIHandle handle,

int timeout)


timeout Number of seconds to wait for an event before returning.

If no event occurs within this period then

WaitTimeoutException is thrown.

ReturnsRecordingEvent The recording event returned by the framework.




BadParameterException handle not specified.

WaitTimeoutException No event has occurred within the specified

timeout.

This synchronous method will block until a recording event is received fromEventra or a network failure occurs. The RecordingEvent returned will containdetails of the generated event.

The event attribute on the RecordingEvent should be matched to one of

the recording event constants defined in the RecordingAPI class (e.g.

RECORD_*) to determine the type of recording event that has been returned.

The API has a maximum event queue size (currently 100). If the queuereaches the maximum -because the getRecordingEvent function has not

been called often enough, then the oldest event on the queue will be

discarded.See the Notification Events section above for more details on handlingevents and the event classes.





Start Recording

startRecording

Note that recording in Eventra is ultimately controlled by recording policieswhich specify the criteria which a call must satisfy for it to be recorded.Therefore even if an API startRecording request is successfully sent, the

recording will be not be made if the call information does not satisfy an activerecording policy.

public void startRecording (RecordingAPIHandle handle, RecordingEvent

evt)


evt RecordingEvent Containing the information needed to start

a recording.




BadParameterException no handle or insufficient event details

specified to start a recording.


Initiates a request to start a recording on a particular Eventra channel asspecified in the lineName attribute of the passed evt parameter.

All information specified in the evt parameter will be tagged to the recording

when it is inserted into the database.

Possible notification events generated by this request include:

RECORD_START_CTI Recording has started

RECORD_FAIL_BAD_NAME Start recording failed because of an invalid

channel name

RECORD_FAIL_HARDWARE Start recording failed because channel

hardware is faulty.

In addition, these RECORD_STOP events could occur any time after a

recording has been started

RECORD_STOP_CTI Recording has been stopped by an external

stopRecording API call.





RECORD_STOP_VOX Recording stopped by energy detection on

a channel e.g. no voice detected.

RECORD_STOP_DTMF Recording stopped due to detection of a DTMF

abort code.

RECORD_STOP_SHORT Recording discarded because it is less than theminimum allowed recording duration.





Stop Recording

stopRecording

Sends a request to stop a recording on a specified channelpublic stopRecording(RecordingAPIHandle handle, String channel)


channel Name of recording channel to stop recording


BadHandleException Invalid handle (e.g. open not yet called, orhandle already closed).

BadParameterException handle and/or channel not specified.


Stops a recording on the specified Eventra channel. The recording will besaved and added to the Eventra database along with any tag informationalready provided (e.g. in startRecording or with tagCurrentCall

methods).

Possible events generated by this request, include:

RECORD_STOP_CTI Recording has stopped

RECORD_FAIL_BAD_NAME Request failed because of an invalid

channel name

RECORD_STOP_FAILED Stop recording failed as channel is not

recording.

RECORD_STOP_SHORT Recording has stopped but too short to

store in DB.





stopRecordingDiscardpublic void stopRecordingDiscard(RecordingAPIHandle handle, String

channel)


channel Name of recording channel to stop recording






Stops a recording on the specified Eventra channel. The recording will bediscarded and will not be added to the database.


RECORD_STOP_DISCARD Recording has stopped & been discarded.


channel name

RECORD_STOP_FAILED Stop recording failed as channel is not

recording

RECORD_STOP_SHORT Recording has stopped but too short to

store in DB.





Tag Call

Sends a request to add information to a recording.

tagCallpublic void tagCall (RecordingAPiHandle handle, String channel,

String digits, String campaign, String host)


channel Name of channel to tag recording on.

digits Digits to associate with the call

campaign Campaign identifier, typically this will be the DDI

digits of an incoming call

host Any text information to add to the call






Initiates a request to tag information to a recording in progress on thespecified Eventra channel.

If the specified channel is not being recorded then recording will be started onthat channel.



channel name

RECORD_START_CTI Recording tagged.





tagCurrentCallpublic void tagCurrentCall (RecordingAPIHandle handle, RecordingEvent

evt)


evt The recording event which contains the call tag info to

be applied to the current call.






Initiates a request to tag information to a recording in progress on thespecified Eventra channel.

The information will be applied to the call currently recording on thelineName attribute specified in RecordingEvent. Any non-blank attributesin the event will over-write any existing values stored by Eventra for that call.



channel name

RECORD_START_CTI Recording tagged.





tagFinishedCallpublic void tagFinishedCall (RecordingAPIHandle handle,

RecordingEvent evt)


evt The recording event which contains the call tag info to

be applied to the finished call.






This function is used to add call information to the database entry for apreviously recorded call.

The call to be tagged must be specified by the lineName (channel) and

dateTime (start date/time) attributes passed in the RecordingEvent class.

Any non-blank fields in the RecordingEventwill over-write any existingvalues for that call.



channel name





Transfer Call

callTransferredpublic void callTransferred (RecordingAPIHandle handle,

RecordingEvent evt, String fromExt, String fromAgent)


evt The recording event which contains the information for

the call to be transferred to.

fromExt Extension number of the call to be transferred.

fromAgent Agent ID. of the call to be transferred.

Throws

RecordingAPiException unexpected error thrown by API.



BadParameterException handle and/or evt and/or fromExt and/or

fromAgent not specified.


This function notifies Eventra that a call has been transferred from one

extension to another. If the call is being recorded the recording will bestopped. A new recording will be started for the transferred call.



channel name

RECORD_STOP_CTI Recording has stopped for call being

transferred.

RECORD_START_CTI Recording has started for new transferred

call.





PCIDSS

PCI DSS is a new directive from Barclaycard that is being adoptedworldwide. It states that the 3 digit security code cannot be stored anywhere.

To facilitate this it is possible to mute or pause a call.If the call is muted then it will be tagged with a ‘PCIDSS Mute’ category for theduration of the call or if the call is subsequently un-muted. This category willprevent the tagged period of the call being listened to by a user, Privilegedusers with supervisor rights will be able to temporarily un-mute the call butcannot remove the tag.

If a call is paused, then it will be tagged with a ‘PCIDSS Pause’ category forthat period until the call is subsequently restarted or the duration of the call. Inthis instance the paused section of the call will not be available to any user.

muteCallpublic void muteCall (RecordingAPIHandle handle, RecordingEvent evt)


evt Identifies the call to be muted using the lineName and

extension attributes.




BadParameterException handle and/or lineName and ext not specified.


Initiates a request to mute a recording in progress.

The mute will be applied to the call currently identified by the specifiedlineName and extension.



channel name

RECORD_MUTED Recording muted.

RECORD_MUTE_FAILED Mute on Recording has failed.





unMuteCallpublic void unMuteCall (RecordingAPIHandle handle, RecordingEvent

evt)

Parameters

handle Handle returned by previous call to open method.

evt Identifies the call to be un-muted using the lineName and





BadParameterException handle and/or linename and ext not specified.


Initiates a request to un-mute a recording in progress which has beenpreviously muted.

The un-mute will be applied to the call identified by the specified lineNameand extension.


RECORD_FAIL_BAD_NAME

Request failed because of an invalidchannel name

RECORD_UNMUTED Recording un-muted.

RECORD_UNMUTE_FAILED Un-Mute on Recording has failed





pauseCallpublic void pauseCall (RecordingAPIHandle handle, RecordingEvent evt)


evt Identifies the call to be paused using the lineName and







Initiates a request to pause a recording in progress.

The pause will be applied to the call identified by the specified lineName andextension.


RECORD_FAIL_BAD_NAME Request failed because of an invalidchannel name

RECORD_PAUSED Recording Paused.

RECORD_PAUSE_FAILED Pause on Recording has failed





restartCallpublic void restartCall (RecordingAPIHandle handle, RecordingEvent

evt)


evt Identifies the call to be restarted using the lineName

and extension attributes.






Initiates a request to restart a recording in progress which has beenpreviously paused.

The restart will be applied to the call identified by the specified lineName andextension.



channel name

RECORD_UNPAUSED Recording Restarted.

RECORD_UNPAUSE_FAILED Restart on Recording has failed





Appendix A – Example

An example of starting and stopping a recording:

import com.tisl.eventra.recordingapi.RecordingAPI;import com.tisl.eventra.recordingapi.RecordingAPIHandle;

import com.tisl.eventra.recordingapi.event.RecordingEvent;

import com.tisl.eventra.recordingapi.exception.*;

public class ExampleStartAndStopRecording {

// default private constructor.

private ExampleStartAndStopRecording() {

}

public static void main(String []args) {

RecordingAPIHandle apiHandle=null;

int timeout=30; // event timeout.

System.out.println("started ExampleStartAndStopRecording ...");

// open a connection to Recording API.

try {

apiHandle = RecordingAPI.open("example client");

try {

// setup the call info and start recording.

RecordingEvent callInfo = new RecordingEvent();

callInfo.setLineName("4101");

callInfo.setExt("4101");

callInfo.setAgent("5422");

callInfo.setDialledDigits("01883 343009");

callInfo.setDirection(RecordingAPI.CALL_DIRECTION_INBOUND);callInfo.setHost("api test call");

RecordingAPI.startRecording(apiHandle, callInfo);

/* get next recording event to confirm start, timeout after 30

seconds. */

RecordingEvent recEvt =

RecordingAPI.getRecordingEvent(apiHandle, timeout);

if (recEvt!=null &&

recEvt.getEvent()==RecordingAPI.RECORD_START_CTI) {

System.out.println("Started recording

partcallid="+recEvt.getAppPartCallId()+" on

"+recEvt.getLineName());

// now stop recording.

try {

RecordingAPI.stopRecording(apiHandle,

recEvt.getLineName());

// get event to confirm stop.

RecordingEvent recEvt2=

RecordingAPI.getRecordingEvent(apiHandle,timeout);

if (recEvt2!=null &&

recEvt2.getEvent()==RecordingAPI.RECORD_STOP_CTI) {

System.out.println("Stopped recording

partcallid="+recEvt2.getAppPartCallId()+" on

"+recEvt2.getLineName());}

else {





System.out.println("Stop failed, expected event

not returned.");

}

}

catch (RecordingAPIException e) {

System.out.println("Stop failed: "+e);

}

}else {

System.out.println("Start failed, expected event not

returned.");

}

} catch (RecordingAPIException e) {

System.out.println(" failed to start a recording: "+e);

}

}


System.out.println("Failed to connect to Eventra Recording API:

"+e);

}

finally {

// ensure connection is closed on exit.

if (apiHandle!=null) {

try {

RecordingAPI.close(apiHandle);

}


System.out.println("failed to close API connection:

"+e);

}

}

}

System.out.println("completed ExampleStartAndStopRecording.");

}

}

Documents

Eventra Java Recording API