Custom JSON Format Keywords

Keywords mark the places in a custom encoder or decoder format where GENESIS reads or writes a piece of information. This topic lists every keyword, grouped by the format it can be used in. For background on custom formats see IoT Message Encoders and Decoders; for the steps to build one see Creating a Custom JSON Decoder.

A keyword is written between percent signs and placed where the corresponding value belongs in the JSON:

{ "id": "%PUBLISHNAME%", "v": "%VALUE%", "q": "%STATUS.GOOD%", "t": "%NOWUTC.UNIX%" }

In Workbench, click (Add keyword) beside any format field to open the Keyword Selection Form and insert a keyword from the list valid for that field.

Value Format

The value format describes one value entry. It applies to the whole message when the message type is One value for each message, and to each entry in the array for the other value message types.

Keyword

Description

%VALUE%

The value of the point (string).

%PUBLISHNAME%

The name under which the point is published (string).

%DEVICENAME%

The name of the device (string).

%DATATYPE%

The data type of the point (string), for example Int16.

%DESCRIPTION%

Point description property (string).

%UNITS%

Point units property (string).

%FORMAT%

Point format property (string).

%HIGHRANGE%

High range of the point analog range property (double).

%LOWRANGE%

Low range of the point analog range property (double).

%ACCESSRIGHTS%

Point access rights property (byte): 1 = READ, 2 = WRITE, 3 = READ WRITE.

%ENCODER%

The encoder name (string).

%DATASET%

The object or array of objects is interpreted as a dataset (table).

%MEMBER%

A complex object wrapping properties such as value and description. Each property is exposed as its own point. Valid for decoders only.

%TIMESTAMP.TEXT%

The timestamp of the value (string), for example 2017-03-22T17:09:44.5348262+01:00.

%TIMESTAMP.TICKS%

The timestamp of the value (long), for example 636257795760626391.

%TIMESTAMP.UNIX%

The timestamp of the value in milliseconds since 1 January 1970 (long).

%NOWLOCAL.TEXT%

The local timestamp (string), for example 2017-03-22T17:09:44.5348262+01:00.

%NOWLOCAL.TICKS%

The local timestamp (long), for example 636257795760626391.

%NOWLOCAL.UNIX%

The local timestamp in milliseconds since 1 January 1970 (long).

%NOWUTC.TEXT%

The UTC timestamp (string), for example 2017-03-22T17:09:44.5348262+01:00.

%NOWUTC.TICKS%

The UTC timestamp (long), for example 636257795760626391.

%NOWUTC.UNIX%

The UTC timestamp in milliseconds since 1 January 1970 (long).

%STATUS.GOOD%

True if the quality of the point is good, false otherwise (boolean).

%STATUS.TEXT%

The quality of the point (string), for example Good - From Cache.

%STATUS.CODE%

The code identifying the quality of the point (integer), for example 0x00000007.

%STATUS.OPCQUALITY%

The quality of the point converted to a classic OPC code (integer).

The format supplied by (Set default format) is:

{ "id": "%PUBLISHNAME%", "v": "%VALUE%", "q": "%STATUS.GOOD%", "t": "%NOWUTC.UNIX%" }

Message Format

The message format describes the object that wraps the values. It is editable when the message type is Multiple values in the "Values" array of the message, and reflects the value format automatically for the other message types.

Keyword

Description

%VALUE_ARRAY%

The array of values encapsulated in the message. The value format is applied to each entry.

%DEVICENAME%

The name of the device (string).

%ENCODER%

The encoder name (string).

%NOWLOCAL.TEXT%

The local timestamp (string).

%NOWLOCAL.TICKS%

The local timestamp (long).

%NOWLOCAL.UNIX%

The local timestamp in milliseconds since 1 January 1970 (long).

%NOWUTC.TEXT%

The UTC timestamp (string).

%NOWUTC.TICKS%

The UTC timestamp (long).

%NOWUTC.UNIX%

The UTC timestamp in milliseconds since 1 January 1970 (long).

The format supplied by (Set default format) is:

{ "timestamp": "%NOWUTC.UNIX%", "values": "%VALUE_ARRAY%" }

Write Format

The write format describes the messages GENESIS sends back to a device, and is an optional override of the default format. It accepts the same keywords as the message format: %VALUE_ARRAY%, %DEVICENAME%, %ENCODER%, and the %NOWLOCAL.*% and %NOWUTC.*% timestamps.

Birth and Will Messages

The birth and will message bodies defined on an MQTT broker accept two keywords.

Keyword

Description

%DEVICENAME%

The name of the device (string).

%ENCODER%

The encoder name (string).