# Update a Ledger Entry

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

  • In your personal Ledger.
  • In a Ledger based on the account UUID. You will only be able to update Entries in a Ledger where your Role allows you to update Entries.

Any optional parameters not provided in the request will be left unchanged.

Method Path Operation*
PATCH /twins/{twin}/ledgers/personal update_twin_ledger_entry
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.

# Request

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. This field cannot be changed by the User if the "ref" (reference) field is part of the value.
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.

*

Any optional parameters not provided in the request will be left unchanged. Any optional parameters provided in the request will replace current parameters.

# Response

Attribute Type Description
entry_created_ts timestamp Last time when an Entry in the Ledger was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
entry_updated_ts timestamp Last time when an Entry in the Ledger was updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
value_changed_ts timestamp Last time when a value of an Entry in the Ledger was changed. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
entries dictionary Key-value pairs:
- Key: alphanumeric string unique within the Ledger. It must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,127}$.
- Value: Valid JSON data type.
indexes * list of strings List of names of Indexes tables. An Indexes table is listed if the Ledger meets the conditions of the Indexes table and is in the Indexes table.

*

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

# Entry attributes

Attribute Type Description
value valid JSON data type User-defined value of the Entry. This field cannot be changed by the User if the "ref" (reference) field exists.
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.
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 Entry was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
history
optional
string Time for which the history of changes of the Entry's value is to be stored. If the value of the "history" attribute is null, the time period is defined as inf (infinite). The limit of stored historical values of an Entry is 1000. If there are more than 1000 Entry value changes within the specified time period, only 1000 most recent Entry values will be stored. If there is no "history" attribute, the history service is not enabled and historical Entry values are not stored. The value of the "history" attribute must match the regular expression (opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.
ref object
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 "not_found" or "ok" Status of the reference. It can have one of the following values:
- "not_found": The value could not be found. "not_found" is the default value until the value in the Entry that the reference is pointing to is first updated. It can also mean that the value is set to null as the Entry that the reference is pointing to does not exist or is not accessible to the account, because there is a circular reference or because there are too many transfers between references (the maximum number of hops allowed is 32).
- "ok": The Entry value is consistent with the value that the reference is pointing to.
include string Entry is an external const-like value fetched upon request.
timeseries * object
Timeseries attribute. It holds the name of the Timeseries table, the "measurement" attribute, and (optionally) the "dimensions" attribute.
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: Value of the given dimension.
publish dictionary
Holds the details about the Notifications set up for the given Entry.
Attribute Type Description
rule string Notification Rule that defines the conditions to be met for a notification to be sent
topic list List of notification topic templates

*

You can use the "timeseries" attribute if the Timeseries service is enabled for your account.

IMPORTANT NOTE

Please note that once you create an Entry where the "value" is picked up through a "reference" from another Entry, you cannot update the Entry so that it does not contain a "reference". In such case, you would need to delete the Entry and create a new Entry without the "reference" field.

# Status codes

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