# 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:
- Timeseries*:
"timestamp"
,"dimensions"
, and"measurements"
. - Indexes:
"properties"
. - Notifications:
"topic"
.
*
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.
← Rules Custom headers →