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???

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.

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

---

API Name?

Request URL	/recording-label-definitions/{labelDefinitionId} (Use the path attribute from the response returned by the GET or POST operations for label definition.)
HTTP method	PUT
Required Features:	Roles: Supervisor, Agent Permissions: RECORDING_PERMISSION_ADD_LABEL_DEFINITION

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

---

API Name?

Request URL	/recording-label-definitions/{labelDefinitionId}
HTTP method	DELETE
Required Features:	Roles: Supervisor, Agent Permissions: RECORDING_PERMISSION_DELETE_LABEL_DEFINITION

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

---

API Name?

Request URL	/recording-label-definitions/{labelDefinitionId}
HTTP method	DELETE
Required Features:	Roles: CC Admin, Supervisor, Agent Permissions: None.

Parameters (why not use "Payload" as done previously?)
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"
    }
  ]
}