Introduction

5 min read

 

Concept

Overview

A Ledger is a JSON document that consists of multiple Entries following a key-value scheme. It is at the Entry level that the access to and its visibility are managed.

There are three types of Entries. The Entry type depends on the origin of the value stored in an Entry:

• an Entry of value type stores a value provided directly by the account,
• an Entry of reference type stores a reference to a value from a different Ledger,
• An Entry of include type stores a reference to a value from a different Ledger belonging to the same account.

Entries of different types can be used to create relationships between objects (i.e., object graphs).
Read more: Ledger structure

Include type Entry

An include type Entry allows to point to a source Entry (another Entry from which the value should be taken). The source Entry needs to be an Entry from a different Ledger belonging to the same account. 

Each time there is a reading of a Ledger, if there is an Entry of include type in that Ledger, the value is taken from the source Entry. However, a copy of the value is never stored in the Ledger with the Entry of include type. 

In case the value of the source Entry is changed, there is no notification sent to the Entry of include type.

 

Include type Entries should be considered as a way to refer to global values used, for example, in rules.
Read more: Rules

Reference type Entry

A reference type Entry allows to point to an Entry in another Ledger from which the Entry value should be taken (source Entry). This Entry can be an Entry belonging to a foreign Ledger, i.e., a Ledger belonging to a different account. Before accessing a value located in a foreign Ledger, a check of the visibility rule is performed each time in the referenced source Entry.

Each time the value of the source Entry is changed, the value is copied to the reference type Entry.

 

Conceptually, a change to a value of an Entry of reference type resulting from a change to a source Entry’s value is analogous to a change made by a user as a result of an API call. All actions configured for a given Entry (e.g., publish, indexes, timeseries) will be executed. Therefore, an Entry of reference type should be treated as a way to build relationships (e.g., graphs) which will be updated automatically and which can be used to trigger actions initiated by a change to an Entry’s value.

The Trusted Twin platform supports cascading reference updates, in particular, automatic detection of circular references.

Tips & tricks

• Entries of include type are best used for referencing global variables.
• Entries of reference type are best used for building graphs of interrelated objects that are updated in real-time.
• When creating visibility rules for source Entries, please bear in mind that the updates of their values are initiated by the system. Therefore, some variables related to the user are not available for use in these rules.

• If you want to create a history of Entry value changes for Entries for your own purposes, create a reference ("ref") type Entry and enable the History service for that Entry.

Developer resources
Rules