Recording Label APIs

ENTIRE PAGE IS NEW

The following APIs are accessible at the base path /api/v2
For example, http://localhost:8080/api/v2/recordings<recid>

Pre-requisite

Set Elasticsearch schema v2 in Interaction Recording Web Services, to enable it to use labels and non-deletion features. For existing deployments, follow the migration steps here: Migrating an Existing Elasticsearch Deployment to Schema V2). New deployments after GIR version 8.5.2xx.xx (TBD) will have Elasticsearch schema v2 enabled by default.

Permissions

See: Configuring Permissions for Recording Labels

Overview

Use this API to create and administer label definitions and label recordings.
A Label Definition provides the basic definition of a label, with a name, displayName and description.
A Label can then be added to a voice recording by referring to the name of the label definition.

API Name? ...or is this a generic description of all API?

Request URL	/recordings/{id}
HTTP method	POST
Required features	schema-elasticsearch-v2-call-recording schema-elasticsearch-v2-screen-recording

Payload
Attribute	JSON Data Type	Mandatory	Possible Values	Default Value	Description	Notes
operationName	String	yes	applyNonDelete	N/A	Mark a recording for non-deletion.	If it is for a voice recording, all the associated screen recordings at the time of the operation will also be updated.

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request URL	/path/path/path/
HTTP method	POST
Required Features:	Roles: Supervisor, Agent Permissions: XXXXXXXXXXXXXXXXXXXX

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Name?

Request URL	/recordings/<recid>/labels
HTTP method	POST
Required Features:	Roles: Supervisor, Agent Permissions: RECORDING_PERMISSION_ADD_LABEL

Payload
Properties	Type	Mandatory	Default Values	Description
name	String	Yes	N/A	The name of the label definition to be added to the recordings.
content	JSON Object	No	empty	The content associated with the label to be added to the recordings. This is a free-form JSON element that accepts valid JSON types.

Example

Add a Label to a Recording Payload

201 CREATED
{
  "statusCode": 0,
  "id": "8c9a634f-343d-49b3-8322-b571be520b31",
  "uri": "http://127.0.0.1/api/v2/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31",
  "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
}
  
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Cannot add label to recording."
}

API Name?

Request URL	/recording-labels
HTTP method	POST
Required Features:	Roles: Supervisor, Agent Permissions: RECORDING_PERMISSION_ADD_LABEL

Payload
Level-0 Properties	Level-1 Properties	Type	Mandatory	Default Values	Description
recordingIds	N/A	JSON Array	Yes	N/A	The list of recording IDs that the label needs to be added to.
label	name	String	Yes	N/A	The name of the label to be added to the recordings.
	content	JSON Object	No	empty	The content associated with the label to be added to the recordings. This is a free-form JSON element that accepts valid JSON types.

Example

Add Label To Recordings Payload Example 
 
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "text" :  "This is an awesome comment!" 
     } 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "importantTag" 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "rating" :  "excellent" , 
       "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
       } 
     } 
   } 
}

Response

HTTP Status	Situations
200 OK	The requested list of recordings is empty.
201 CREATED	The label has been added to all the requested recordings successfully and at least one label resource has been Created.
207 MULTI-STATUS	The label failed to be added to some but not all of the requested recordings, but succeeded for the rest.
403 FORBIDDEN	The label failed to be added to all of the requested recordings.

The response of the API reports both succeeded and failed cases:

Fields	Type	Mandatory	Possible Values	Situations	Notes
statusCode	Integer	yes	0 (Ok)	The label is added to all the requested recordings successfully.
			7 (PartialResponse)	The label succeeded on some of the requested recordings, but failed on the rest.
			13 (UnableToCreateResource)	The label failed to be added to all the requested recordings.
statusMessage	String	no	not specified a message providing information		The statusMessage will provide more information about a failure if statusCode is not 0.
succeeded	JSON Array	yes	The recording id to created label URI mapping for the recordings to which label has been successfully added.	It will always be displayed in the response but can be empty.
failed	JSON Array	yes	A list of blocks that describes the failures.	It will always be displayed in the response but can be empty.

---

API Name?

Request URL	/recordings/<recid>/labels/<id>
HTTP method	PUT
Required Features:	Roles: CC Admin, Supervisor, Agent Permissions: RECORDING_PERMISSION_ADD_LABEL

Properties	Type	Mandatory	Default Values	Description
content	JSON Object	No	empty	The content associated with the label to be updated to the recordings. This is a JSON object which can be customized depending on the application. The examples below show a possible use-case of adding user comments on a recording.

Example

Update Label To a Recording Payload

PUT /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "text" :  "This is an awesome comment!" 
   } 
} 
   
PUT /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/5dbdb466-5377-4351-bd1e-c4066437d410 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "rating" :  "excellent" 
     "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
     } 
   } 
}

Effect

By updating a label, in addition to the content of the label being updated to the one that is specified in the payload, the following will also be updated:

Fields New Value createTime The time when the update action was performed. createUser The username of the user who requested the update.

Response

HTTP Status Situations 200 OK the requested label has been updated successfully 403 FORBIDDEN • the recording requested can be found but the label cannot be updated to it for whatever reason(e.g., region not matched, requesting user cannot access the recording) • the recording requested cannot be found 404 NOT FOUND the requested label cannot be found

Fields Type Mandatory Possible Values Situations Notes statusCode Integer yes 0 (Ok) the label has been updated to the requested recording successfully 6 (ResourceNotFound) the label cannot be found 15 (UnableToUpdateResource) • the recording requested can be found but the label cannot be updated to it for whatever reason(e.g. region not matched, requesting user cannot access the recording) • the recording requested cannot be found statusMessage String no • not specified; • a message providing information The statusMessage will provide more information about a failure if statusCode is not 0.

Example

Update Label To a Recording Response

200 OK 
{ 
   "statusCode" : 0 
} 
  
403 FORBIDDEN 
{ 
   "statusCode" : 15, 
   "statusMessage" :  "Cannot update the label for recording." 
} 
   
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Requested label cannot be found." 
}