# Rules
# Rules overview
A rule on the Trusted Twin platform is used to manage visibility and access of a user to a resource, to define conditions triggering a notification event or to select Twins for a given Indexes database table.
Rules are used in:
- Roles: Rules control user's access to a
"twin", an"identity", or an"entry"of a Leger. They are held in the"rules"attribute of a role. - Identities: Rules control visibility of Identities for users from foreign accounts (Identities are by default visible to users from the account that created the Identity). They are held in the
"visibility"attribute of an Identity. - Ledger Entries:
- Rules that control visibility of Entries of a Ledger. Such a rule is held in the
"visibility"attribute of an Entry of a Ledger. - Rules that define the condition triggering a notification event. Such a rule is held in the
"publish"attribute of an Entry of a Ledger.
- Rules that control visibility of Entries of a Ledger. Such a rule is held in the
- Indexes to select Twins for a given Indexes database table.
Rules can be null. The interpretation of null differs for role rules and for visibility rules:
- Role rule: If the rule is
null, the user does not have access to Twins and Ledger Entries in foreign accounts. - Visibility rule: If the rule is
null, the Identity (or Entry of a Ledger) is only visible to users of the account that created the Identity (or Entry of a Ledger).
# Rule syntax
Rules follow the Rule Engine Syntax(opens new window).
# Rule variables
The set of variables available to create rules varies based on the object where the rules are created.
IMPORTANT NOTE
Missing variables (not set, not existing, or not available) resolve to None.
# System variables
| Variable name | Type | Description | Twin rule (Role) | Identity rule (Role) | Entry rule (Role) | Visibility (Identity) | Visibility (Ledger Entry) | Publish (Ledger Entry) |
|---|---|---|---|---|---|---|---|---|
| account | string | Account UUID performing the given API operation. | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| twin | string | Twin UUID. | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| identity | string | Identity. | ✓ | ✓ | ||||
| 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. | ✓ | ✓ | ✓ | |||
| operation | string | Name of API operation. For a full list of operations, please see the List of endpoints section. | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| cause | string, value is "user" or "system" | Cause of a task. Value can be "user" (for tasks generated by user) or "system" (for system-generated tasks). | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| now | timestamp (float) | Current time. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
*
Not available in system tasks.
**
Ledger UUID of the Ledger where the operation is being performed. It is available only for Ledger-related operations.
# Twin variables
| Variable name | Type | Description | Twin rule (Role) | Identity rule (Role) | Entry rule (Role) | Visibility (Identity) | Visibility (Ledger Entry) | Publish (Ledger Entry) |
|---|---|---|---|---|---|---|---|---|
| twin_status | string, value is "alive" or "terminated" | Status of the Twin. In case of alive Twins, the "description" can be updated by the owner of the Twin. In case of terminated Twins, the "description" cannot be updated. Ledger Entries, Identities and Docs can be attached to alive and terminated Twins by all users involved in the process. | ✓ | ✓ | ✓ | ✓ | ||
| 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. 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. For more details consult the description field section. | ✓ | ✓ | ✓ | ✓ |
*
To access dictionary type variables, use the . separator.
# Identity variables
| Variable name | Type | Description | Twin rule (Role) | Identity rule (Role) | Entry rule (Role) | Visibility (Identity) | Visibility (Ledger Entry) | Publish (Ledger Entry) |
|---|---|---|---|---|---|---|---|---|
| identity_owner | string | Account UUID of the account that owns the Identity. | ✓ |
# Ledger variables
| Variable name | Type | Description | Twin rule (Role) | Identity rule (Role) | Entry rule (Role) | Visibility (Identity) | Visibility (Ledger Entry) | Publish (Ledger Entry) |
|---|---|---|---|---|---|---|---|---|
| entry_name | string | Name of the Entry of a Ledger. | ✓ | ✓ | ✓ | |||
| entry_value | valid JSON data type | Value of the Entry of a Ledger. | ✓ | ✓ | ✓ | |||
| entry_new_value | valid JSON data type | Value of the Entry of a Ledger after Entry update. | ✓ | |||||
| entry_old_value | valid JSON data type | Value of the Entry of a Ledger before Entry update. | ✓ | |||||
| 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 "visibility", "history", "timeseries", or "publish" property of an Entry 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). | ✓ | ✓ | ✓ | |||
| 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. | ✓ | ✓ | ✓ |
*
To access dictionary type variables, use the . separator.
# User variables
| Variable name | Type | Description | Twin rule (Role) | Identity rule (Role) | Entry rule (Role) | Visibility (Identity) | Visibility (Ledger Entry) | Publish (Ledger Entry) |
|---|---|---|---|---|---|---|---|---|
| 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. | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| auth_type | string, value is "secret" or "token" | Authorization type used by the calling user. Value can be "secret" (denoting authorization with a User Secret or a User Token. | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
*
To access dictionary type variables, use the . separator.
# Custom header variables
| Variable name | Type | Description | Twin rule (Role) | Identity rule (Role) | Entry rule (Role) | Visibility (Identity) | Visibility (Ledger Entry) | Publish (Ledger Entry) |
|---|---|---|---|---|---|---|---|---|
| DICT* | dictionary | Value of the X-TrustedTwin header. | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
*
To access dictionary type variables, use the . separator.
# Built-in functions
The following built-in functions are available on the Trusted Twin platform:
| Built-in function | Description | Example | Result |
|---|---|---|---|
| DTFISO | Converts string in ISO format into datetime object. | $DTFISO['2023-04-03'] | 2023-04-03 00:00:00 |
| DTFTS | Converts timestamp into datetime object with UTC time zone. | $DTFTS[1680516155.471] | 2023-04-03 10:02:35 |
| TDFS | Converts seconds into datetime object. | $TDFS[1680516155] | 19450 days, 10:02:35 |
| HASH | Computes a hash value. Available parameters: -data (mandatory): String to be hashed. -key (optional): Hashing key (string). | $HASH('name@example.com', 'key_123') | 9jq3MhUJ_J31avqSxX8beqbcCu-t |
| ABS | Returns the absolute value of the provided number. | $ABS(-9) | 9 |
| ANY | Returns the boolean 'True' if every member of the array argument is truthy. | $ANY([1,2,3,4,5,6,0]) | True |
| ALL | Returns the boolean 'True' if any member of the array argument is truthy. | $ALL([1,2,3,4,5,6,0]) | False |
| SPLIT | Splits the string value into substrings. | $SPLIT('Lorem ipsum') | ('Lorem', 'ipsum') |
| MAX | Converts a list or a set to its maximum element. | $MAX([1,2,3,4,5,6]) | 6.0 |
| MIN | Converts a list or a set to its minimum element. | $MIN([1,2,3,4,5,6]) | 1 |
| SUM | Converts a list or a set to the sum of its elements. | $SUM([1,2,3,4,5,6]) | 21.0 |
| AVR | Converts a list or a set to the average of its elements. | $AVR([1,2,3,4,5,6]) | 3.5 |
| LEN | Converts a list or a set to the length of its elements. | $LEN([1,2,3,4,5,6]) | 6 |
# Example usage
For examples of usage of rules on the Trusted Twin platform, please see our feature guides:
- Rules (Entry visibility) feature guide
- Rules (Twin rule) feature guide
Was this article helpful?