/metadata

Use /metadata to add, update, or delete transcript metadata values. /metadata supports PATCH and DELETE requests. PATCH adds or modifies metadata values. DELETE removes metadata values.

Synopsis

PATCH /metadata/$co_short/$org_short/$tId?token=$token --data @$fields.json
DELETE /metadata/$co_short/$org_short/$tId?token=$token --data @$fields.json

$co_short: Company short name used to filter the request.
$org_short: Organization short name used to filter the request.
$tId: UUID for the transcript to be queried.
$token: Authorization token with the required read or write permissions for the request.
$fields.json: JSON-formatted data that specifies the metadata to be changed. The required JSON data varies by HTTP method. PATCH requests must include a JSON-formatted object literal of metadata key-value pairs. DELETE requests must include a JSON-formatted array of metadata field names. This JSON data may be submitted in the body of the request or with a file. Due to the JSON's potential complexity, using a file is recommended.

Using `/metadata`

Metadata is a core component of processing files in V‑Spark, and it's important to note the following behavior and potential ramifications when using the /metadata endpoint.

Metadata storage. V‑Spark writes metadata changes to three places: the database, Elasticsearch, and long-term storage. Metadata is saved to the database and to Elasticsearch only if that metadata field has been configured for the transcript's folder.
Metadata modification. Any request to /metadata updates the last_modified field associated with the request's tId.
Adding new metadata fields. Requests to /metadata do not change a folder's metadata field configuration. As a result, to add new custom metadata key-value pairs that are indexed and searchable, the new metadata fields must be added to the transcript's folder configuration before the request is made.
Values for non-configured fields. Values for fields specified in the request but not configured for the folder are not stored in the database nor in Elasticsearch. However, when metadata fields and values for non-configured fields are submitted using /metadata, those fields and values are not lost; they are passed through and saved in the JSON transcript in long-term storage only.
Application processing. Changing a transcript's metadata with /metadata does not trigger transcript-application reprocessing.
Reserved fields. Requests with metadata field names in the reserved list are rejected.
Multiple requests. Making multiple /metadata requests for the same tId at the exact same time may result in an error with HTTP code 400 and an Error uploading metadata message. The solution in this case is to retry the request.

Content types


Method	Expects	Returns
PATCH	application/json (object literal)	text/html application/json
DELETE	application/json (array litera)	text/html application/json
Errors		text/html

PATCH and DELETE requests return success messages with HTTP code 200 and the full updated metadata result for the transcript with the "application/json" MIME type.

Example requests

The following example PATCH /metadata request specifies a tId of 3 associated with the company Co-Short and the organization Org-Short. The request includes a JSON object with one key-value pair.

curl -H 'Content-type: application/json' -d '{"agentgroup":"2"}' -X PATCH 'http://example.com:3000/metadata/Co-Short/Org-Short/3?token=123'

The following example PATCH /metadata request is similar to the preceding example, but specifies a file named fields.json for the request's JSON data.

curl -H 'Content-type: application/json' -d @fields.json -X PATCH 'http://example.com:3000/metadata/Co-Short/Org-Short/3?token=123'

The following example DELETE /metadata request specifies a tId of 6 associated with the company Co-Short and the organization Org-Short. The request includes a JSON array with one field name, transfers, to be deleted from the transcript.

curl -H 'Content-type: application/json' -d '["transfers"]' -X DELETE 'http://example.com:3000/metadata/Co-Short/Org-Short/6?token=123'

Upon success, the preceding examples return JSON data containing the full updated metadata for the specified transcript.

Example input

The following example JSON shows the format required for PATCH requests.

{
    "direction":"inbound",
    "hold time":"78",
    "transfers":"3"
}

On a successful PATCH request, the keys and values for the direction, hold time, and transfers fields are added to a tId associated with a folder that has these fields configured. If those metadata fields are already associated with that tId, the values for those fields are updated.

The following example JSON shows the format required for DELETE requests.

[
    "clientname",
    "agentname",
    "employeegroup"
]

On a successful DELETE request, the preceding example removes metadata fields and values for the clientname, agentname, and employeegroup elements from the database, Elasticsearch, and long-term storage for the specified tId.