Revision as of 22:12, February 17, 2017 by Sschlich (talk | contribs) (→‎{{Editgrn_open}}API Name?{{Editgrn_close}})
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???

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

Updating Label Definitions

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

Deleting Label Definitions

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

Retrieving Label Definitions

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 back for the label definition path is always returned Using "*" returns all fields

Response

HTTP Status Fields Possible Values Situations
200 OK statusCode 0 (Ok) the retrieval of all the label definitions succeeded
7 (PartialResponse) the retrieval of some of the label definitions failed
12 (UnableToRetrieveResource) the retrieval of all the label definitions failed
labelDefinitions an array of label definitions if fields parameter is present, labelDefinitions will be 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"
    }
  ]
}
Comments or questions about this documentation? Contact us for support!