# Update Twin Ledger Entry

This endpoint updates one or multiple Ledger Entries. You can update Ledger Entries:

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

Any optional parameters not provided in the request will remain unchanged.

Method Path Operation*
PATCH /twins/{twin}/ledgers/{ledger}** update_twin_ledger_entry

*

In order for a user to perform the "update_twin_ledger_entry" operation, the "update_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

# Value type Entry

Parameter Type In Description
twin
required		 string path Twin UUID.
ledger
required*		 string path Ledger UUID.
value
optional**		 valid JSON data type body User-defined value of the Entry.
visibility
optional**		 string 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 "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).

**

  • Any optional parameters not provided in the request will be left unchanged.
  • Any optional parameters provided in the request will replace current parameters.
  • Operations replacing any current "visibility", "timeseries", or "publish" parameters with values equal to current parameter values will result in an update to the "entry_updated_ts" timestamp.
  • Operations replacing the value of the current "value" parameter with the same value will result in an update to the "value_changed_ts" timestamp.

***

If there is no "history" parameter in the request, no changed will be made to the History service.
If the "history" parameter value is replaced with value equal to current parameter value, the update will result in an update to the "entry_updated_ts" timestamp.
If the value of the "history" parameter is set to null, the History service will be disabled for the given Entry.
If "history" is set to "INF", the most recent 1000 historical Entry values will be stored for the Entry.
If "history" 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).

# Reference type Entry

Parameter Type In Description
twin
required		 string path Twin UUID.
ledger
required*		 string path Ledger UUID.
visibility
optional**		 string 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 "ledger" parameter is required in the path of the request for requests based on the account UUID. In such a case, the Twin rule needs to allow you to perform operations on the given Twin.

**

  • Any optional parameters not provided in the request will be left unchanged.
  • Any optional parameters provided in the request will replace current parameters.
  • Operations replacing any current "visibility", "timeseries", or "publish" parameters with values equal to current parameter values will result in an update to the "entry_updated_ts" timestamp.

***

If there is no "history" parameter in the request, no changes will be made to the History service.
If the "history" parameter value is replaced with value equal to current parameter values will result in an update to the "entry_updated_ts" timestamp.
If the value of the "history" parameter is set to null, the History service will be disabled for the given Entry.
If "history" is set to "INF", the most recent 1000 historical Entry values will be stored for the Entry.
If "history" 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).

# Include type Entry

Parameter Type In Description
twin
required		 string path Twin UUID.
ledger
required*		 string path Ledger UUID.
visibility
optional**		 string 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 "ledger" parameter is required in the path of the request for requests based on the account UUID. In such a case, the Twin rule needs to allow you to perform operations on the given Twin.

**

  • Any optional parameters not provided in the request will be left unchanged.
  • Any optional parameters provided in the request will replace current parameters.
  • Operations replacing the current "visibility" parameter with values equal to current parameter values will result in an update to the "entry_updated_ts" timestamp.

# 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 field cannot be changed by a user 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. 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** string Entry is an external const-like value fetched upon request.
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.

IMPORTANT NOTE

Please note that once you create an Entry, the type of the Entry (whether it is a value, include or reference type Entry) cannot be changed. You would need to delete the Entry and create a new Entry of a different type.

# Status codes

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

← Delete Twin Ledger Entry →

Was this article helpful?