Introduction

Concept

Shared process

Trusted Twin is a developer platform for operational data sharing. It allows customers to store and handle shared objects used in shared processes. 

Shared processes are processes that go beyond a single organization’s scope. They involve multiple, independent partners from various organizations. Shared processes operate on objects that are common for all the cooperating partners. Therefore, these objects are called shared objects.

Shared object

Overview

Shared objects aggregate in real-time operational data essential to the process. The data are provided and used by all partners. As partners can contribute their data independently, the structure of a shared object must be dynamic. In addition, because a shared object is built from data owned by many partners, it has to allow for continuous visibility and access management.

Shared objects on the Trusted Twin platform are inspired by the digital twin concept. Therefore, the main object on the platform, which ties together data provided by partners and acts as a conceptual “bracket” for the data, is called a Twin.

Twin

A Twin is the main object of the Trusted Twin platform because it ties together all data provided by partners participating in a shared business process. It acts as a conceptual “bracket” for the data.

A Twin can be created by any account on the Trusted Twin platform. The account which created the Twin becomes the owner of the Twin.

Developer resources
Create a Twin

As the Twin is a “bracket”, it does not store any account’s data. It consists mainly of a public identifier (UUID) and a public description. Any account that knows the  identifier (UUID) of a Twin can access the Twin and its description.

Developer resources
Get a Twin

The Twin owner is the only account allowed to change the Twin description.

Developer resources
Update a Twin

The Twin owner is also the only account allowed to terminate the Twin. Twin termination results in Twin’s status change to “terminated”. However, the Twin is not deleted from the Trusted Twin platform as long as there is data associated with it (i.e., Ledgers or Docs). Partners can still contribute their data to a Twin with the status “terminated”.

Any account that knows the Twin’s identifier (UUID) can contribute to the Twin and read data from it. 

There are three types of objects related directly to a Twin that accounts can use to store their data. These objects are Identities, Ledgers, and Docs. 

All these objects are subject to visibility and access management.
Read more: Data access and visibility

Identity

Identities are used to convert any user-defined identifier into a Twin identifier (UUID). Each account can add multiple private or public Identities to a single Twin.

Developer resources
Create an Identity

Ledger

Ledgers are used to store information about the state of a Twin. Each account can have exactly one Ledger associated with a single Twin. 

A Ledger consists of multiple Entries following a key-value scheme. The value can store any JSON serializable object. Data visibility and access are managed on the Ledger Entry level. 

The value can be provided directly by the account, through a reference to a value of a different, especially foreign Ledger (value is updated automatically), or through a reference to a different Ledger of the same account (value is not updated automatically).
Read more: Ledger structure

Developer resources
Ledger and Ledger Entry structure

Doc

Docs are static files of any type (e.g., PDF, CSV, XLS) and size. Each account can attach multiple Docs to a single Twin.
Read more: File storage (Docs)

Developer resources
Attach a Doc

Tips & tricks

• Identities must be unique only within the Twin context. Therefore, the same Identity can be added by the same account to many Twins. You can resolve an Identity to identify groups of Twins (the group size is limited to ca. 100 Twins).

Developer resources
Resolve an Identity

• Ledger Entries of reference type can be used to build graphs of connected Twins which are automatically updated.
  Read more: Ledger structure
  Read more: Object linking
• Ledger entries of include type can be used to model global parameters or variables.
  Read more: Ledger structure
  Read more: Object linking
• The Indexes service allows for building structured views of the state of multiple Twins in the form of relational database tables. The service configuration allows for setting a Rule for Twin selection as well as the properties (i.e., Ledger Entry values) reflected in the index.
  Read more: Indexes and Timeseries

Developer resources
Indexes service

• The Timeseries service allows for building structured views of the history of multiple Twins in the form of relational database tables. The service configuration allows for selecting Twins, dimensions, and measurements (i.e., Ledger Entry values) reflected in the Timeseries database table.
  Read more: Indexes and Timeseries

Developer resources
Timeseries service