Recording Label API

ENTIRE PAGE IS NEW

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

Prerequisites

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: a name, a displayName, and a description.
A Label can then be added to a voice recording by referring to the name of the label definition.

Access this API and its Operations at the base path /api/v2. For example:
http://localhost:8080/api/v2/recording_label_definitions

Creating label definitions

Method	Path	Required Roles	Required Permissions	Notes
POST	/recording-label-definitions/	Supervisor Agent	RECORDING_PERMISSION_ADD_LABEL_DEFINITION	Create the label definition, if it does not already exist.

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
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.
			18 (ResourceAlreadyExists)		A label definition with the same name exists already.
			20 (unauthenticated)		The requesting user is ops.
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 an 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
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.
			6 (ResourceNotFound)		The specified label definition cannot be found.
			20 (Unauthenticated)		The requesting user is ops.
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": 6,
	"statusMessage": "Custom label definition cannot be found."
}

{
	"statusCode": 20,
	"statusMessage": "Access denied."
}

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.

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.
			6 (ResourceNotFound)		The specified label definition cannot be found.
			20 (Unauthorized)		The requesting user is ops.
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 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 definition path 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"
    }
  ]
}

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

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

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

Method	Path	Required Roles	Required Permissions
DELETE	/recordings/<recid>/labels/<id>	*Supervisor Agent	RECORDING_PERMISSION_DELETE_LABEL

Payload table here?

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.
statusCode	Integer	yes	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." 
}

Getting all labels from a recording

Method	Path	Required Roles	Required Permissions	Notes
GET	/recordings/<recid>/labels	CC Admin Supervisor Agent	N/A

Parameters Payload?
Attributes	JSON Data Type	Mandatory	Possible Values	Default Value	Description
fields	comma-separated string of fields	no	namecreateTimecreateUsercontent	N/A	The fields to be returned back for the label definition. If the fields parameter is set, then uri, path and id are always returned regardless if they are specified or not. When the fields parameter is set, the response will contain an array of labels with the selected fields. If the fields parameter is not set, then an array of paths and an array of uris is returned instead. If the fields value is set to "*", all the fields will be returned in the response.

Response

HTTP Status	Situations
200 OK	The retrieval of the labels succeeded or there are no labels associated with the recording
403 FORBIDDEN	The recording for which the labels are requested can be found but cannot be retrieved for some reason (e.g., region not matched, requesting user cannot access the recording). The recording for which the labels are requested cannot be found.

Payload

Fields

Subfields

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 to the same recording.

statusMessage

String

no

not specified
a message providing information

The statusMessage will provide more information about a failure if statusCode is not 0.

labels

array of labels

no

Each label will have the fields requested.