Revision as of 23:46, February 17, 2017 by Sschlich (talk | contribs) (→‎Adding a Label to multiple Recordings)
Jump to: navigation, search

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

Adding Labels to Recordings

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

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

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."
    }
  ]
}
Comments or questions about this documentation? Contact us for support!