/processing/dictionary/read

Downloads a given dictionary instance, or provides a list of available dictionary instances.

The user must be authenticated and have read permissions to the associated site group.

Request

The request object has the following fields:

Name	Type	Required	Description
`dictionaryId`	String	No	Identifies a given dictionary instance to retrieve.
`siteGroupId`	String	No	Identifies a site group with which zero or more dictionary instances are associated.

The dictionaryId and siteGroupId fields are mutually exclusive, only one of them can be provided.

Since the amount of dictionary data can be significant, the actual dictionary data is only returned for some types of requests. The rules are as follows:

If dictionaryId is provided, all dictionary data and meta data for the identified dictionary is returned.
If siteGroupId is provided, meta data for all dictionaries associated with the identified site group is returned. The dictionary data itself is not returned. To return the actual dictionary data, specify dictionaryId explicitly instead of siteGroupId.
If neither dictionaryId nor siteGroupId are provided, meta data for all dictionaries that the user has read access to is returned. The dictionary data itself is not returned.
If both dictionaryId and siteGroupId are provided, an error message will be returned.

Response

The response object has the following fields:

Name	Type	Description
`dictionaries`	Array of Object	An array of dictionary detail objects, as described below.

A dictionary detail object has the following fields:

Name	Type	Description
`dictionaryId`	String	The identifier for the dictionary instance.
`siteGroupId`	String	The site group to which the dictionary logically belongs.
`name`	String	A brief description of the dictionary's purpose and function.
`description`	String	A longer description of the dictionary's purpose and function.
`lastUpdatedAt`	String (Date)	An ISO 8601 timestamp that tells when the dictionary's data was last updated.
`lastUpdatedBy`	String	Identifies the user that last updated the dictionary's data.
`createdAt`	String (Date)	An ISO 8601 timestamp that tells when the dictionary was first created.
`createdBy`	String	Identifies the user that first created the dictionary.
`workbook`	String (Binary)	The dictionary data provided as a base-64 encoded Excel workbook.
`entries`	Object	The dictionary data provided as a JSON object.

The workbook and entries fields are mutually exclusive, and will not both be present. Which of these two fields, if any, that is returned depends on how the dictionary data was originally provided.

"error": "Invalid request: Unexpected type detected." $ cx.py /processing/dictionary/read '{"dictionaryId":"1234"}'{"error": "Invalid request: Unexpected type detected."}Your dictionary is stored in an old format that is not backwards compatible with current API. Contact Cxense Support to get help to download your dictionary.

As shown in the examples below, the jq command line utility is useful for manipulating JSON data. E.g., to extract the workbook data and save it as an Excel file.

Examples

Bash

$ cx.py /processing/dictionary
{
 "dictionaries": [
 {
 "createdAt": "2011-06-06T15:34:06.068Z",
 "createdBy": "foo@bar.com",
 "lastUpdatedAt": "2012-10-31T21:05:44.258Z",
 "lastUpdatedBy": "bilbo.baggins@theshire.net",
 "siteGroupId": "1767213656410",
 "description": "Detects all hobbits.",
 "dictionaryId": "92222535422192674",
 "name": "hobbit-fun"
 },
 {
 "createdAt": "2012-09-07T14:53:01.169Z",
 "createdBy": "foo@bar.com",
 "lastUpdatedAt": "2012-10-02T15:37:01.182Z",
 "lastUpdatedBy": "barbarella@fonda.com",
 "siteGroupId": "9235425",
 "description": "Science fiction galore.",
 "dictionaryId": "92222535422192674",
 "name": "Duran Duran"
 },
 {
 "createdAt": "2012-03-19T17:25:42.463Z",
 "createdBy": "abc@xyz.com",
 "lastUpdatedAt": "2012-10-02T15:36:06.640Z",
 "lastUpdatedBy": "example@foo.com",
 "siteGroupId": "173898230",
 "description": "I like turtles!",
 "dictionaryId": "7222278089845354",
 "name": "Teenage mutant ninja turtles"
 }
 ]
}

Bash

$ cx.py /processing/dictionary '{"siteGroupId":"2468013579"}'
{
 "dictionaries": [
 {
 "createdAt": "2013-02-14T11:22:52.820Z",
 "createdBy": "boo@hoo.com",
 "lastUpdatedAt": "2013-02-14T11:39:50.706Z",
 "lastUpdatedBy": "boo@hoo.com",
 "siteGroupId": "2468013579",
 "description": "A decent description goes here.",
 "dictionaryId": "92223077212454939",
 "name": "Boo's special dictionary"
 },
 {
 "createdAt": "2013-02-15T12:22:52.820Z",
 "createdBy": "boo@hoo.com",
 "lastUpdatedAt": "2013-02-15T12:39:50.706Z",
 "lastUpdatedBy": "boo@hoo.com",
 "siteGroupId": "2468013579",
 "description": "So long and thanks for all the fish.",
 "dictionaryId": "92223077212454939",
 "name": "Douglas Adams words"
 }
 ]
}

Bash

$ # Download the dictionary data and meta data.
$ cx.py /processing/dictionary/read '{"dictionaryId":"92223077212454939"}' > mydictionary.json

$ # If the dictionary data was provided as an Excel workbook, we can easily convert
$ # it back into the original binary *.xlsx file.
$ cat mydictionary.json | jq -r '.dictionaries[].workbook' | base64 --decode > myworkbook.xlsx

$ # If we just want to look at the dictionary's meta data, we can suppress the
$ # dictionary's data before we look at it.
$ cat mydictionary.json | jq '.dictionaries[].workbook = ""'
{
 "dictionaries": [
 {
 "createdAt": "2013-02-14T11:22:52.820Z",
 "createdBy": "boo@hoo.com",
 "lastUpdatedAt": "2013-02-14T11:39:50.706Z",
 "lastUpdatedBy": "boo@hoo.com",
 "siteGroupId": "2468013579",
 "description": "A decent description goes here.",
 "dictionaryId": "92223077212454939",
 "name": "Boo's special dictionary",
 "workbook": ""
 }
 ]
}

Bash

$ # Download the dictionary data and meta data. This dictionary's data
$ # was provided as a JSON object, so that's what gets emitted.
$ cx.py /processing/dictionary/read '{"dictionaryId":"123454321"}' | jq .
{
 "dictionaries": [
 {
 "dictionaryId": "123454321",
 "siteGroupId": "246808642",
 "name": "My silly dictionary",
 "description": "A decent description goes here.",
 "lastUpdatedAt": "2015-01-27T12:19:31.465Z",
 "lastUpdatedBy": "foo@bar.com",
 "createdAt": "2015-01-27T11:23:14.481Z",
 "createdBy": "foo@bar.com",
 "entries": {
 "global-properties": {
 "tokenizer-context": "en",
 "mode": "overlap",
 "key-normalization-flags": 4,
 "value-normalization-flags": 4,
 "swap-fields": true,
 "count": 2,
 "unique-count": 1
 },
 "xyz-colors": {
 "banana": [
 "yellow",
 "brown"
 ],
 "coconut": "brown",
 "apple": [
 "green",
 "red"
 ],
 "orange": "orange",
 "pear": "green"
 }
 }
 }
 ]
}

Last updated: December 28, 2023