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

Was this article helpful?