# Templates

# Templates overview

A template on the Trusted Twin platform is used every time when it is necessary to return a value or a name that is not known in advance.

Templates are used in:

*

Available in general configuration and in Ledger Entry configuration.

# Template syntax

The templates on the Trusted Twin platform follow the Python string str.format() convention (see Format String Syntax (opens new window)).

In case of lists and objects, to access sub-items two interchangeable conventions can be used:

# Template types

There are two template types - value and name templates:

  • Tokens used in a value template are replaced by a valid JSON representation of a given value of an item from the Available variables dictionary.
  • Tokens used in a name template are replaced by a valid string representation of a given value of an item from the Available variables dictionary.

In most cases, string and JSON representations are similar. The only difference is the string type value which is represented in quotation marks ("") for value templates and without quotation marks for name templates:

Type Example Value template Name template
string example name "x" "example name \"x\"" example name "x"
number 123.45 123.45 123.45
object {"a": 1} {"a": 1} {"a": 1}
array [1, 2, 3] [1, 2, 3] [1, 2, 3]
boolean true true true
null null null null

For example, a template {LEDGER.str_entry}_{num_entry} will be resolved to Gdansk_123 in case of a name template or to "Gdansk"_123 in case of a value template.

# Available templates

Name Template type Used in Description
"timestamp" Value template Timeseries and Ledger Template that defines the value of the timestamp.
"dimensions" Value template Timeseries and Ledger Template that defines the value for each of the dimensions.
"measurements" Name template Timeseries and Ledger Template that defines the name of the measurement column to store the Entry value.
"properties" Value template Indexes Template containing a list of property names and a list of data types of the corresponding properties.
"topic" Name template Notifications Template that defines the name of the subscription topic.

# Available variables

Below you can find variables that can be used in templates:

Variable name Type Description "timestamp" "dimensions" "measurement" "properties" "topic"
System
account string Account UUID performing the given API operation. ✓ ✓ ✓ ✓ ✓
twin string Twin UUID. ✓ ✓ ✓ ✓ ✓
ledger string Ledger UUID. The Ledger UUID is equal to the account UUID if the operation is performed by a user belonging to an account which owns the Ledger. ✓ ✓ ✓ ✓ ✓
user* string User UUID performing the given API operation. ✓ ✓ ✓ ✓ ✓
role* string Role UUID performing the given API operation. ✓ ✓ ✓ ✓ ✓
now timestamp (float) Current time. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window). ✓ ✓ ✓ ✓ ✓
Twin
twin_status string, value is "alive" or "terminated" Status of the Twin.
twin_owner string Account UUID of the account that owns the Twin.
twin_creator string Account UUID of the account that created the Twin.
twin_created_ts timestamp (float) Time at which the Twin was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
twin_updated_ts timestamp (float) Time at which the Twin was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
TWIN** dictionary Description of the Twin which consists of user-defined key-value pairs:
- key: Must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
- value: Valid JSON data type.
For more details consult the description field section.
Ledger
entry_name string Name of the Entry of a Ledger. ✓ ✓ ✓ ✓ ✓
entry_value valid JSON data type Value of the Entry of a Ledger. ✓ ✓ ✓ ✓ ✓
entry_created_ts timestamp (float) Time at which the Entry of a Ledger was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window). ✓ ✓ ✓ ✓ ✓
entry_updated_ts timestamp (float) Time at which the key of the Entry of a Ledger was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window). ✓ ✓ ✓ ✓ ✓
entry_changed_ts timestamp (float) Time at which the value of the Entry of a Ledger was last changed. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window). ✓ ✓ ✓ ✓ ✓
entry_new_value valid JSON data type New value of the Entry (after the change to the Entry value). ✓
entry_old_value valid JSON data type Old value of the Entry (before the change to the Entry value). ✓
ledger_created_ts timestamp (float) Last time when an Entry in the Ledger was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
ledger_updated_ts timestamp (float) Last time when the Ledger was updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
ledger_changed_ts timestamp (float) Last time when a value of an Entry in the Ledger was changed. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
LEDGER** dictionary The value of the key-value pair:
- Key: alphanumeric string unique within the Ledger. It must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
- value: Valid JSON data type.
User
user_name* string Name of the user. It must match the regular expression (opens new window) [0-9A-Za-z][0-9A-Za-z_ \-]{0,30}[0-9A-Za-z]. It does not need to be unique in the context of an account.
USER** dictionary Description of the user which consists of user-defined key-value pairs:
- key: Must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
- value: Valid JSON data type.

*

Not available in system tasks.

**

To access dictionary type variables, use the . separator or [] brackets.

← Custom headers →