Revision as of 18:27, February 22, 2017 by Sschlich (talk | contribs) (→‎Response)
Jump to: navigation, search

Recording Label API

ENTIRE PAGE IS NEW

Source: https://intranet.genesys.com/display/RP/Summary+of+Label+APIs+to+be+documented


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.

Creating Label Definitions

Method Path Required Roles Required Permissions Notes
POST /recording-label-definitions/
  • Supervisor
  • Agent
 RECORDING_PERMISSION_ADD_LABEL_DEFINITION


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.

Label Definitions

Creating Label Definitions

Request URL /api/v2/recording-label-definitions
HTTP method POST
Required Features: Roles: Supervisor, Agent

Permissions: RECORDING_PERMISSION_ADD_LABEL_DEFINITION


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
name String yes N/A The name of the label definition
  • Is case-sensitive
  • Must only contain ASCII characters
  • Must be unique among other label definitions
  • Must not start with two underscores("__") as it is reserved
displayName String no defaults to the value of name The display name of the label definition
description String no empty string The description of the label definition


Example

{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }


Response

HTTP Status
Status Codes Situations Notes
201 CREATED The label definition was created successfully
400 BAD REQUEST Bad Request received
403 FORBIDDEN Forbidden to create the label definition
409 CONFLICT The label definition was not created as one with the same name exists already


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer yes 0 N/A label definition was created
1 (RequiredParameterMissing) The required payload attributes are missing.
2 (InvalidRequestParameter) The constraints of payload attributes are not met.
3 (OperationForbidden) The requesting user does not have the permissions required or is attempting to create with reserved name.
5 (Unauthorized) The requesting user does not have the roles required
18 (ResourceAlreadyExists) If a label definition with the same name exists already
statusMessage String no
  • not specified;
  • a message providing information
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition JSON object no JSON object containing the label definition
  • path (string): The path to the resource
  • name (string): The name of the label definition
  • displayName (string, optional): The display name of the label definition
  • description (string, optional): The description of the label definition
 N/A The newly created label definition or existing one in case of attempt to create an already existing one.

Examples

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "New Label Definition",
		"description": "A new label definition"
	}
}
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
{
	"statusCode": 18,
	"statusMessage": "Resource exists already",
	"labelDefinition": {
		"path": "/recording-label-definitions/a6a6f1d9-788a-47b4-bdeb-80b3d598cfa6",
		"name": "ExistingLabelDefinition",
		"displayName": "Existing Label Definition",
		"description": "An existing label definition"
	}
}

Updating Label Definitions

Method Path Required Roles Required Permissions
PUT /recording-label-definitions/{labelDefinitionId}
  • Supervisor
  • Agent
 RECORDING_PERMISSION_ADD_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
name String yes N/A The name of the label definition
  • Name cannot be updated—must be specified to the same value as the existing name.
displayName String no default to the value of name if not specified The display name of the label definition
description String no empty string The description of the label definition

Example

{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }


Response

HTTP Status
Status Codes Situations Notes
200 OK The label definition was updated successfully
400 BAD REQUEST Bad Request received
403 FORBIDDEN Forbidden to update the label definition
404 NOT FOUND Cannot find the label definition to update


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer yes 0 N/A label definition was updated
1 (RequiredParameterMissing) The required payload attributes are missing
2 (InvalidRequestParameter) The constraints of payload attributes are not met
3 (OperationForbidden) The requesting user does not have the permissions

required or is attempting to update with different name

5 (Unauthorized) The requesting user does not have the roles required
6 (ResourceNotFound) The specified label definition cannot be found
statusMessage String no
  • not specified;
  • a message providing information
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition JSON object yes
  • name (string): The name of the label definition
  • displayName (string, optional): The display name of the label definition
  • description (string, optional): The description of the label definition
  • path (string, optional): The path of the label definition
 N/A

Examples

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "Updated Label Definition",
		"description": "An updated label definition"
	}
}
 
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 5,
	"statusMessage": "Access denied."
}
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

Deleting Label Definitions

Method Path Required Roles Required Permissions
DELETE /recording-label-definitions/{labelDefinitionId}
  • Supervisor
  • Agent
 RECORDING_PERMISSION_DELETE_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.


STEVE ASKS: WHY IS THERE NO PAYLOAD TABLE HERE?


Response

Status Codes
HTTP Status
Situations Notes
200 OK The label definition was deleted successfully.
403 FORBIDDEN Forbidden to delete the label definition.
404 NOT FOUND Cannot find the label definition to delete.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer yes 0 N/A The label definition was deleted.
3 (OperationForbidden) The requesting user does not have the permissions required.
5 (Unauthorized) The requesting user does not have the roles required.
6 (ResourceNotFound) The specified label definition cannot be found.
statusMessage String no
  • not specified;
  • a message providing information
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.

Examples

{
	"statusCode": 0
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 5,
	"statusMessage": "Access denied."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

Retrieving Label Definitions

Method Path Required Roles Required Permissions Notes
GET /recording-label-definitions
  • CC Admin
  • Supervisor
  • Agent
 N/A Returns all the label definitions.


Parameters (why not "Payload"?)
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
fields comma-separated string of fields no
  • name

displayName
description

N/A The fields to be returned from the label definitionpath are always returned.

Use "*" to return all fields.

Response

HTTP Status Fields Possible Values Situations
200 OK statusCode 0 (Ok) Retrieval of all label definitions succeeded.
7 (PartialResponse) Retrieval of some label definitions failed.
12 (UnableToRetrieveResource) Retrieval of all label definitions failed.
labelDefinitions An array of label definitions If the fields parameter is present, labelDefinitions is shown in the response, but it can be empty:
  • Fields parameter could not be retrieved.
paths An array of paths to label definitions. If the fields parameter is absent, the paths of all label definitions are returned.


Label Definition response data

Fields Description
name the name of the label definition
path the path of the label definition
displayName the display name of the label definition
description the description of the label definition

Examples

200 OK
GET /recording-label-definitions
{
  "statusCode": 0,
  "paths": [
    "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
    "/recording-label-definitions/bc34345a-da45-4436-a1d8-ecffad0aedd4",
    "/recording-label-definitions/cf9dc6f8-639b-4132-a85c-3d9b984e1120",
    "/recording-label-definitions/68b3219c-6e18-4ad8-af80-87bbc4078bfc",
    "/recording-label-definitions/1a64ae51-28d6-41e5-b3b8-3d179f71ea79"
  ]
}
 
GET /recording-label-definitions?fields=*
{
  "statusCode": 0,
  "labelDefinitions": [
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?fields=name,displayName
{
  "statusCode": 0,
  "labelDefinitions": [
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "displayName": "Comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "displayName": "Important"
    }
  ]
}

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Recording Label Operations

Adding Labels to Recordings

Adding a Label to a Recording

Method Path Required Roles Required Permissions

POST

/recordings/<recid>/labels

  • Supervisor
  • Agent
 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."
}

Response

HTTP Status Situations
201 CREATED the label has been added to the recording successfully
403 FORBIDDEN
  • The recording requested can be found but label cannot be added to it for whatever reason (e.g. region not matched, requesting user cannot access the recording)
  • The recording requested cannot be found
  • A label instance already exists that is identical to the one to add on the same recording
  • The label definition name cannot be found.
Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok)
  • The label was added to the requested recording successfully
13 (UnableToCreateResource)
  • The label failed to be added to the requested recording
18 (ResourceAlreadyExists) there already exists a label instance that is identical to

the one to add on the same recording

statusMessage String no
  • not specified
  • message providing information
 The statusMessage will provide more information about a failure if statusCode is not 0.
id String no id of the created label HTTP status is 201
path String no path of the created label HTTP status is 201
uri String no uri of the created label HTTP status is 201


Example

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

Method Path Required Roles Required Permissions
POST /recording-labels
  • Supervisor
  • Agent
 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: ???

Payload
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.

Updating a Label on a Recording

Method Path Required Roles Required Permissions
PUT /recordings/<labels> *CC Admin
  • Supervisor
  • Agent
 RECORDING_PERMISSION_ADD_LABEL


Payload
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

When a label is updated:

  • The content of the label is updated to the one that is specified in the payload.
  • The field createTime is updated to the time when the update action was performed.
  • The field createUser is updated to 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.


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

Deleting a Label from a Recording

API Name?

Request URL /recordings/<recid>/labels/<id>
HTTP method DELETE
Required Features: Roles: Supervisor, Agent

Permissions: RECORDING_PERMISSION_DELETE_LABEL

Response

HTTP Status Situations
200 OK
  • The label has been deleted from the requested recording successfully.
403 FORBIDDEN
    • The recording requested can be found but the label cannot be deleted from it for some reason (e.g., region not matched, requesting user cannot access the recording).
    • The recording requested cannot be found.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok)
  • The label has been deleted from the requested recording

successfully
or

  • The label cannot be found within the requested recording.
14 (UnableToDeleteResource) The label failed to be deleted from the requested recording.
statusMessage String no
  • not specified;
  • a message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.

Example

Delete Label Instance From Recording Response 

DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0 
} 
   
DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31 
403 FORBIDDEN 
{ 
   "statusCode" : 14, 
   "statusMessage" :  "Label failed to be deleted from the recording." 
}
Comments or questions about this documentation? Contact us for support!