Add Twin Ledger Entry

This endpoint adds one or multiple Entries to a Ledger. You can add Entries:

• to your personal Ledger.
• based on the account UUID if the Twin rule allows you to perform operations on the given Twin.

Method	Path	Operation*
POST	/twins/{twin}/ledgers/{ledger}**	add_twin_ledger_entry

*

In order for a user to perform the "add_twin_ledger_entry" operation, the "add_twin_ledger_entry" permission must be included in the list of allowed actions in the statement of the user's role.

**

The "ledger" parameter in the path of the request should point to the Ledger resource for requests based on the account UUID. Request based on the account UUID can be performed if the Twin rule allows you to perform operations on the given Twin. For requests on personal Ledger, you can use personal instead of the Ledger UUID in the path of the request (/twins/{twin}/ledgers/personal).

Request

IMPORTANT NOTE

You can create Entries of value, reference, and include type. Please note that you cannot update the Entry type the once it has been created.

Parameter	Type	In	Description
twin required	string	path	Twin UUID.
ledger required*	string	path	Ledger UUID.
entries required	dictionary	body	Key-value pairs: - key: alphanumeric string unique within the Ledger. It must match the regular expression(opens new window) (_*[a-z0-9]+)([_-][0-9a-z]+). - value: Valid JSON data type.

*

The "ledger" parameter in the path of the request should point to the Ledger resource for requests based on the account UUID. Request based on the account UUID can be performed if the Twin rule allows you to perform operations on the given Twin. For requests on personal Ledger, you can use personal instead of the Ledger UUID in the path of the request (/twins/{twin}/ledgers/personal).

Value type Entry parameters

Parameter	Type	In	Description
value required*	valid JSON data type	body	User-defined value of the Entry. This field cannot be changed by a user for reference and include type Entries.
visibility optional**	string, DEFAULT=null	body	Visibility of the Entry. If the "visibility" of an Entry is null, the Entry is private. Private Entries are only visible to users of the account that owns the Ledger. If all Entries of the Ledger are private, the Ledger is private. If the "visibility" of an Entry is not null, the Entry is public. Public Entries are visible to users of the account that owns the Ledger and also visible to users of other accounts if the visibility rule evaluates to True. If any of the Entries of the Ledger is public, the Ledger is public.
history optional***	string	body	Time for which the history of changes of the Entry's value is to be stored.The "history" value must match the regular expression(opens new window).^([1-9][0-9]{0,2}[DWMY])|(INF)$. The limit of stored History records is 1000 per Entry. If there are more than 1000 Entry value changes within the specified time period, only 1000 most recent History records will be stored.
timeseries optional****	dictionary	body	Timeseries attribute. It holds the name of the Timeseries table, the "measurement" attribute, and (optionally) the "dimensions" attribute. Attribute Type In Description measurement string body Name of the measurement column in the given Timeseries table under which the Entry value is to be stored. dimensions dictionary body Key-value pair: - key: name of the dimension under which the Entry value is to be stored. - value: Template for the value of the dimension.
publish optional*****	dictionary	body	Key-value pairs that hold the details about the Notifications set up for the given Entry: - key: Notification rule that defines the conditions to be met for a notification to be sent. - value: List of topics in form of name templates for the given Notification.

*

The "value" parameter is required for value type Entries. For other Entry types, please see reference type Entry parameters and include type Entry parameters.

**

The "visibility" parameter is optional and does not need to be included in the request body when adding Entries. If it is not included in the request body, its default value (DEFAUL=null) is used.

***

The "history" parameter is optional.
If there is no "history" parameter included in the request when adding a Ledger Entry, the History service will not be enabled for the Entry.
If there is no "history" parameter in the request, the History service will not be enabled for the Entry.
If the value of the "history" parameter is set to null, the History service will not be enabled for the Entry.
If the value of the "history" parameter is set to "INF", the most recent 1000 historical Entry values will be stored for the Entry.
If the value of the "history" parameter is set to a time period (e.g., days, weeks, months), the historical Entry values will be stored for the given time period subject to the maximum number of history records limit (1000 per Entry).

****

The "timeseries" parameter is optional. If there is no "timeseries" parameter included in the request, Entry value is not stored in the Timeseries database. In order to use the Timeseries service, it needs to be enabled for your account.

*****

The "publish" parameter is optional. If there is no "publish" parameter included in the request, no Notifications are set for a given Entry.

Reference type Entry parameters

Parameter	Type	In	Description
ref required	dictionary	body	Reference. It allows to create an Entry based on the "value" field of an Entry in a different Ledger, especially a Ledger of a different account. The value that the reference is pointing to must be visible to the account creating the reference. Parameter Type In Description source required* string, composed of {twin} (Twin UUID), {ledger} (Ledger UUID)/ name of the Entry in the Ledger* body Source path to the value that we want the Entry to reference.
visibility optional**	string, DEFAULT=null	body	Visibility of the Entry. If the "visibility" of an Entry is null, the Entry is private. Private Entries are only visible to users of the account that owns the Ledger. If all Entries of the Ledger are private, the Ledger is private. If the "visibility" of an Entry is not null, the Entry is public. Public Entries are visible to users of the account that owns the Ledger and also visible to users of other accounts if the visibility rule evaluates to True. If any of the Entries of the Ledger is public, the Ledger is public.
history optional***	string	body	Time for which the history of changes of the Entry's value is to be stored.The "history" value must match the regular expression(opens new window).^([1-9][0-9]{0,2}[DWMY])|(INF)$. The limit of stored History records is 1000 per Entry. If there are more than 1000 Entry value changes within the specified time period, only 1000 most recent History records will be stored.
timeseries optional****	dictionary	body	Timeseries attribute. It holds the name of the Timeseries table, the "measurement" attribute, and (optionally) the "dimensions" attribute. Attribute Type In Description measurement string body Name of the measurement column in the given Timeseries table under which the Entry value is to be stored. dimensions dictionary body Key-value pair: - key: name of the dimension under which the Entry value is to be stored. - value: Template for the value of the dimension.
publish optional*****	dictionary	body	Key-value pairs that hold the details about the Notifications set up for the given Entry: - key: Notification rule that defines the conditions to be met for a notification to be sent. - value: List of name templates for the given Notification. The "topic" value must match the regular expression(opens new window).^[0-9A-Za-z-_]{0,127}(?😡[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})?$.

*

The "ref" parameter is required for reference type Entries.

**

The "visibility" parameter is optional and does not need to be included in the request body when adding Entries. If it is not included in the request body, its default value (DEFAUL=null) is used.

***

The "history" parameter is optional.
If there is no "history" parameter included in the request when adding a Ledger Entry, the History service will not be enabled for the Entry.
If there is no "history" parameter in the request, the History service will not be enabled for the Entry.
If the value of the "history" parameter is set to null, the History service will not be enabled.
If the value of the "history" parameter is set to "INF", the most recent 1000 historical Entry values will be stored for the Entry.
If the value of the "history" parameter is set to a time period (e.g., days, weeks, months), the historical Entry values will be stored for the given time period subject to the maximum number of history records limit (1000 per Entry).

****

The "timeseries" parameter is optional. If there is no "timeseries" parameter included in the request, Entry value is not stored in the Timeseries database. In order to use the Timeseries service, it needs to be enabled for your account.

*****

The "publish" parameter is optional. If there is no "publish" parameter included in the request, no Notifications are set for a given Entry.

Include type Entry parameters

Parameter	Type	In	Description
include required*	dictionary	body	Include property. It allows to create an Entry that fetches upon request the "value" field of an Entry in a different Ledger in the same account. Parameter Type In Description source required* string, composed of {twin} (Twin UUID)/ name of the Entry in the Ledger* body Source path to the value that we want the Entry to include.
visibility* optional*	string, DEFAUL=null	body	Visibility of the Entry. If the "visibility" of an Entry is null, the Entry is private. Private Entries are only visible to users of the account that owns the Ledger. If all Entries of the Ledger are private, the Ledger is private. If the "visibility" of an Entry is not null, the Entry is public. Public Entries are visible to users of the account that owns the Ledger and also visible to users of other accounts if the visibility rule evaluates to True. If any of the Entries of the Ledger is public, the Ledger is public.

*

The "include" parameter is required for include type Entries.

**

The "visibility" parameter is optional. If it is not included in the request, its default value (DEFAUL=null) is used.

Response

Entry attributes

Attribute	Type	Description
entry_created_ts	timestamp	Time at which the Entry was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
entry_updated_ts	timestamp	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	Time at which the value of an Entry was last changed. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
value	string	User-defined value of the Entry. This value of this field cannot be changed by users for Reference and Include type Entries.
visibility	string	Visibility of the Entry. If the "visibility" of an Entry is null, the Entry is private. Private Entries are only visible to users of the account that owns the Ledger. If all Entries of the Ledger are private, the Ledger is private. If the "visibility" of an Entry is not null, the Entry is public. Public Entries are visible to users of the account that owns the Ledger and also visible to users of other accounts if the visibility rule evaluates to True. If any of the Entries of the Ledger is public, the Ledger is public.
ref*	dictionary	Reference property. It allows to create an Entry based on the "value" field of an Entry in a different Ledger, especially a Ledger of a different account. The value that the reference is pointing to must be visible to the account creating the reference. Attribute Type Description source string, composed of {twin} (Twin UUID), {ledger} (Ledger UUID)/ name of the Entry in the Ledger* Source path to the value that we want the Entry to reference. status enum, value is "created", "ok", "not_found", "loop_detected" or "too_many_hops" Status of the reference. It can have one of the following values: - "created": The Entry was created. - "ok": The Entry value is consistent with the value that the reference is pointing to. - "not_found": The value could not be found. - "loop_detected": The Entry is not accessible to the account because of a circular reference. - "too_many_hops": There are too many transfers between references (the maximum number of hops allowed is 32).
include**	dictionary	Include property. It allows to create an Entry that fetches upon request the "value" field of an Entry in a different Ledger in the same account. Parameter Type In Description source required* string, composed of {twin} (Twin UUID)/ name of the Entry in the Ledger* body Source path to the value that we want the Entry to include.
history	string	Time for which the history of changes of the Entry's value is to be stored. Please note that the limit of stored History records is 1000 per Entry. If there are more than 1000 Entry value changes within the specified time period, only 1000 most recent History records will be stored. The "history" value must match the regular expression(opens new window).^([1-9][0-9]{0,2}[DWMY])|(INF)$. If no "history" attribute is returned in the response, the History service is not enabled. If "history" is set to "INF", the most recent 1000 historical Entry values are stored for the Entry. If "history" is set to a time period (e.g., days, weeks, months), the historical Entry values are stored for the given time period subject to the maximum number of history records limit (1000 per Entry).
timeseries***	dictionary	Timeseries attribute. It holds the name of the Timeseries table, the "measurement" attribute, and (optionally) the "dimensions" attribute. If no "timeseries" attribute is returned in the response, the Entry value is not stored in a Timeseries table. Attribute Type Description measurement string Name of the measurement column in the given Timeseries table under which the Entry value is to be stored. dimensions dictionary Key-value pair: - key: name of the dimension under which the Entry value is to be stored. - value: Template for the value of the dimension.
publish	dictionary	Key-value pairs that hold the details about the Notifications set up for the given Entry: - key: Notification rule that defines the conditions to be met for a notification to be sent. - value: List of name templates for the given Notification. If no "publish" attribute is returned in the response, no notifications are set for the Entry.

*

The "ref" attribute is only returned for reference type Entries.

**

The "include" attribute is only returned for include type Entries.

***

The Timeseries service needs to be enabled for your account. Please contact hello@trustedtwin.com for more details.

Response ('Entry already exists')

NOTE

If you try to add an Entry that already exists, you will receive the message "error": "Entry already exists." for this Entry in the response. However, the response itself will return the 201 Created status code. Please see the below example for more details.

In the example below, we create two Entries - the Entry "krakow" which does not exist in the Ledger yet and the Entry "wroclaw" which already exists in the Ledger.

NOTE

The templates follow the Python string str.format() convention (see Format String Syntax(opens new window)). Therefore, you can use variables in the templates (see Timeseries overview section for a list of available variables). In our example we use the entry_name variable. As a result, the Entry values will be tagged with a dimension which is equal to the name of the Entry (in our example it is"wroclaw").

The response returns the details of the created Entry "krakow" and the message "error": "Entry already exists" for the Entry "wroclaw" which already exists in the Ledger. The status code of the response is 201 Created.

Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.

Status code	Message	Comment
201	Created	If an Entry that you are trying to create already exists, you will receive the error: "error": "Entry already exists." for this Entry in the response.