# 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. It 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:

# System variables

Variable name Type Description "timestamp" "dimensions" "measurement" "properties" "topic"
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 that 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 variables

Variable name Type Description "timestamp" "dimensions" "measurement" "properties" "topic"
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 variables

Variable name Type Description "timestamp" "dimensions" "measurement" "properties" "topic"
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). ✓ ✓ ✓ ✓ ✓
value_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** 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 variables

Variable name Type Description "timestamp" "dimensions" "measurement" "properties" "topic"
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. It 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.

# User Activity Log variables

Variable name Type Description "timestamp" "dimensions" "measurement"
request_uuid string UUID of the request. ✓ ✓ ✓
request_ts timestamp Time of the request. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). ✓ ✓ ✓
user string UUID of the user making the request or of the user who generated the User Token used in the request. ✓ ✓ ✓
operation string Endpoint operation (see List of endpoints). ✓ ✓ ✓
auth_type string Authorization type. Value can be "secret" denoting that a User Secret was used in the request or "token" denoting that a User Token was used in the request. ✓ ✓ ✓
auth_fingerprint string 4 last characters of the User Secret used in the request or of the User Secret of the user who generated the User Token used in the request. ✓ ✓ ✓
auth_validity_ts timestamp Time at which the User Secret used in the request expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). ✓ ✓ ✓
account string UUID of the account of the user making the request or of the user who generated the User Token used in the request. ✓ ✓ ✓
role string UUID of the role of the user making the request or of the user who generated the User Token used in the request. ✓ ✓ ✓
status_code integer Status code of the request (see Status codes). ✓ ✓ ✓
duration float Duration of the request. ✓ ✓ ✓
RESOURCES dictionary Path parameters of the request. ✓ ✓ ✓
PARAMS dictionary Query string parameters of the request. ✓ ✓ ✓
DICT dictionary DICT passed in the X-TrustedTwin custom header or "secret_dict" of the User Token. ✓ ✓ ✓

# Resource Access Log variables

Variable name Type Description "timestamp" "dimensions" "measurement"
request_uuid string UUID of the request. ✓ ✓ ✓
request_ts timestamp (float) Time of the request. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). ✓ ✓ ✓
account string UUID of the account requesting access to the resource. ✓ ✓ ✓
user string UUID of the user requesting access to the resource or of the user who generated the User Token used in the request. ✓ ✓ ✓
role string UUID of the role of the user requesting access to the resource or of the user who generated the User Token used in the request. ✓ ✓ ✓
auth_type string Authorization type. Value can be "secret" denoting that a User Secret was used in the request or "token" denoting that a User Token was used in the request. ✓ ✓ ✓
auth_fingerprint string 4 last characters of the User Secret used in the request or of the User Secret of the user who generated the User Token used in the request. ✓ ✓ ✓
auth_validity_ts timestamp (float) Time at which the User Secret used in the request expires. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). ✓ ✓ ✓
operation string Endpoint operation (see List of endpoints). ✓ ✓ ✓
status_code integer Status code of the request (see Status codes). ✓ ✓ ✓
RESOURCES dictionary Path parameters of the request. ✓ ✓ ✓
PARAMS dictionary Query string parameters of the request. ✓ ✓ ✓
twin string UUID of the accessed Twin. ✓ ✓ ✓
twin_status string, value is "alive" or "terminated" Status of the Twin. ✓ ✓ ✓
twin_owner string UUID of the account owning the Twin. ✓ ✓ ✓
twin_creator string UUID of the account that created the Twin. ✓ ✓ ✓
twin_created_ts timestamp (float) Time when 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 when the Twin was updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). ✓ ✓ ✓
LEDGER dictionary Ledger Entries accessed. ✓ ✓ ✓
DOCS dictionary Docs accessed. ✓ ✓ ✓

← Status codes →

Was this article helpful?