Dictionary

Dictionary is a system element, that stores data as a "key-value" pair or a "key-multiple values" set. Dictionary keys are unique.

Dictionaries can be used to show stats in widgets in a more convenient and readable way, as well as store data that can be used in notifications, state change conditions, and state triggers.

The system also has a special type of dictionaries – dictionaries for monitoring.
Dictionaries are not designed to store large amount of data. Recommended dictionary size – no more than a 1000 entries. However, the system doesn’t have a hard limit on dictionary sizes.

You can configure dictionaries in the Dictionaries section of the system settings.

Dictionaries can be grouped together using Dictionary groups.

Named fields

Every value of the dictionary can be assigned a name. For example, the dictionary that stores the information about water meters could look like this:

named fields
Example of a dictionary with named fields

Named fields can be used when using dictionary values as variables. You can find out more in the Use property values as variables section.

You can assign names to fields only when importing a dictionary from an Excel file. In the current version of SAYMON UI you cannot rename columns.

To import named field, the table should have a format like this:

Name

Serial number

Commissioning

SDM630CT

MKL68JLASKH8

24.03.2021

EMLITE ECA2

GRY9RK635VQM

16.09.2023

SDM120CT

AA8RQPVD3JL8

03.11.2024

You can also create named fields via the REST API with Create dictionary and Update dictionary requests.

Encrypted fields

Fields in the dictionaries can be encrypted. To do this, field name must contain the word password (case insensitive). To change the value of encrypted fields, you must reenter its value in the corresponding field. These values can only be read and used on the server.

encrypted

Internally, encrypted fields look like this:

{
    "content": "{\"john.doe\":\"<<crypt:8D0E4E0C1EFC3D4533005804379270C8:96CB2385E0E693D391DD69A156088C46ACAEBEF2C7266993509723F7ECA7DE42>>\",\"jane.doe\":\"<<crypt:280B6896DECF67A730AC1AE011B254FF:0BF81AAF0B206712967008CA9BC9367C>>\"}",
}
To use encrypted field, you must enable encryption in the server configuration. Without this configuration, the values will not be encrypted, just hidden in the web interface.

Indexing fields

You can access dictionary fields the same way you would access elements of an array. This is used when changing how dictionary values are displayed in property classes and when substituting dictionary values ​​as variables in notification templates, monitoring parameters, state change conditions, and other places in the system.

Dictionaries use the following indexing:

Element index Value

0

Key

1 .. N

Dictionary values. N – number of entries in a dictionary.

N + 1, negative values

undefined.

Dictionary model

Field Type Description

columns

Object

Names of key and values of a dictionary. Only included in the dictionaries with named columns.

Defined as a JSON object in the following format:

"columns": {
    "0": {
        "name": "key_name"
    },
    "1": {
        "name": "value 1 name"
    },
    "2": {
        "name": "value 2 name"
    },
    ...
},
You can skip values in this parameter and leave columns unnamed.

content

String

Dictionary’s key-value or key-array pair in the JSON format.

contentType

String

String containing data type of dictionary’s value. In the current implementation, always contains object.

comment

String

User-defined note about the dictionary.

description

String

Dictionary’s description.

id

String

Dictionary’s ID.

name

String

Dictionary’s name.

Examples

Single value

The example below shows a dictionary for the door sensor.

This example dictionary is meant to be used with a door sensor.The sensor sends values 0 and 1 that correspond with the door being closed and opened respectively. If you use the dictionary with a widget, it will show these values in a human-readable form.

Values and their replacements are specified as a JSON string in the content field.

{
    "name": "Door status",
    "content": "{\"0\":\"Closed\",\"1\":\"Open\"}",
    "description": "Transforms data from sensors in the human-readable form",
    "contentType": "object",
    "id": "66e40169029ed40f1105e599"
}

Multiple values

Example below shows a dictionary that has multiple values for each key. In this dictionary, every employee, has a name, an email address, and an encrypted password associated with them.

To create encrypted fields, add a name containing the word password to the columns (case insensitive).

You should also enable encryption in the encrypt field of the server configuration. If you don’t, these field will be hidden in the dictionaries interface, but not encrypted.

 
{
    "name": "Employees",
    "content": "{\"1\":[\"John Doe\",\"jdoe@example.com\",\"<<crypt:8E993700B6C8BE0CD3849016AF2EF808:0ECB4A66999D516BF80AF91042C7D577>>\"],\"2\":[\"Jane Doe\",\"jdoe@example.com\",\"<<crypt:704FBEF78BF89315840EAF72E9581508:9E984544669ACF7DBCD6C9455360CEB8>>\"]}",
    "description": "List of employees",
    "contentType": "object",
    "columns": {
        "0": {
            "name": "ID"
        },
        "1": {
            "name": "Name"
        },
        "2": {
            "name": "Email"
        },
        "0": {
            "name": "Password"
        }
    },
    "id": "66e411bf029ed40f1105e59a"
},