# Get Twin Ledger Entry
This endpoint allows you to retrieve Ledger Entries. You can retrieve Entries:
Method | Path | Operation* |
---|---|---|
GET | /twins/{twin}/ledgers/{ledger}** | get_twin_ledger_entry |
*
In order for a user to perform the "get_twin_ledger_entry" operation, the "get_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
). For requests on Ledgers where you are the owner of the Twin, you can use owner
instead of the Ledger UUID in the path of the request (/twins/{twin}/ledgers/owner
). For requests on Ledgers where you are the creator of the Twin, you can use creator
instead of the Ledger UUID in the path of the request (/twins/{twin}/ledgers/creator
).
# Request
Parameter | Type | In | Description |
---|---|---|---|
twin required | string | path | Twin UUID. |
ledger required* | string | path | Ledger UUID. |
show_references optional** | boolean, DEFAULT=True | query string | Returns Entries of Reference type. Applicable only to personal Ledger, the value for foreign Ledgers is always False . |
show_public optional** | boolean, DEFAULT=True | query string | Returns public Entries. Applicable only to personal Ledger, the value for foreign Ledgers is always False . |
show_private optional** | boolean, DEFAULT=True | query string | Returns private Entries. Applicable only to personal Ledger, the value for foreign Ledgers is always False . |
entries optional*** | string | query string | Returns the specified Entry. Applicable only to personal Ledger, the value for foreign Ledgers is always False . |
*
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
). For requests on Ledgers where you are the owner of the Twin, you can use owner
instead of the Ledger UUID in the path of the request (/twins/{twin}/ledgers/owner
). For requests on Ledgers where you are the creator of the Twin, you can use creator
instead of the Ledger UUID in the path of the request (/twins/{twin}/ledgers/creator
).
**
The show_references
, show_public
, and show_private
parameters are optional and do not need to be included in the request. If they are not included in the request, their default values are used.
***
The entries
parameter is optional. If it is not included in the request, all Entries visible to the caller are returned.
# 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 for Reference and Include type Entries. | |||||||||
visibility | string | Visibility of the Entry: Private 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.Public Entry: 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 a Ledger is public, the Ledger is public. | |||||||||
ref* | dictionary | Reference. It allows to create an Entry based on the |
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). |
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"
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 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. |
- 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 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.
If you have access to an Entry in a foreign Ledger and request the details of the Entry, the response will return the "entry_created_ts"
, "entry_updated_ts"
, "value_changed_ts"
, and "value"
attributes for the Entry.
# Status codes
Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.
Was this article helpful?