# Rules

# Rules overview

A rule on the Trusted Twin platform is used to manage visibility and access of a user to a resource.

Rules are used in:

  • Roles: Rules control user's access to a "twin" 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 which created the Identity). They are held in the "visibility" attribute of an Identity.
  • Ledger Entries: Rules control visibility of Entries of a Ledger. A rule is held in the "visibility" attribute of an Entry of a Ledger.

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 which 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.

Variable name Type Description Role (Twin) Role (Entry) Visibility (Identity) Visibility (Entry)
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. 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 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).
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 a key of an Entry in 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.
Custom header
DICT** dictionary Value of the X-TrustedTwin header.

*

Not available in system tasks.

**

To access dictionary type variables, use the . separator.

***

Ledger UUID of the Ledger on which the operation is being performed. It is available only for Ledger-related operations.

# Example usage scenarios

For examples of usage of rules on the Trusted Twin platform, please see our Working with rules guide.