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."
}

Adding a Label to multiple Recordings

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

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" 
       } 
     } 
   } 
}

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

In the response of the API, it will report 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 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

Example

200 OK{
  "statusCode": 0,
  "succeeded": [ ],
  "failed": [ ]
}
  
201 CREATED
{
  "statusCode": 0,
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "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"
    },
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "id": "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc",
      "uri": "http://127.0.0.1/api/v2/recordings/76705af9-65d4-46a4-af84-e984ef09ec5d/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc",
      "path": "/recordings/76705af9-65d4-46a4-af84-e984ef09ec5d/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc"
    }
  ],
  "failed": [ ]
}
 
207 MULTI-STATUS
{
  "statusCode": 7,
  "statusMessage": "Add of label failed on some recordings.",
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "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"
    }
  ],
  "failed": [ ]
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    },
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Internal error."
    }
  ]
}
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Add of label failed on all the recordings.",
  "succeeded": [ ],
  "failed": [ ]
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    }
  ]
}