diff --git a/content/developers/api-reference/asset-events-api/index.md b/content/developers/api-reference/asset-events-api/index.md index 80b21289e..02048d29f 100644 --- a/content/developers/api-reference/asset-events-api/index.md +++ b/content/developers/api-reference/asset-events-api/index.md @@ -87,7 +87,7 @@ In a future release, Events will be created independently from Assets. -H "@$HOME/.datatrails/bearer-token.txt" \ -H "Content-type: application/json" \ -d "@/tmp/event.json" \ - https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events \ + https://app.datatrails.ai/archivist/v2/$ASSET_ID/events \ | jq ``` @@ -136,6 +136,73 @@ In a future release, Events will be created independently from Assets. - To query the events jump to [Fetch Specific Events by Identity](#fetch-events-for-a-specific-asset) +### DataTrails Reserved Attributes + +The DataTrails platform has reserved attributes starting with `arc_` to perform specific capabilities. +See [Reserved Attributes](/glossary/reserved-attributes/) for more info. + +### Asset-Event Primary Image + +Asset-Events can use the [Blobs API](/developers/api-reference/blobs-api/) to associate a primary image in the DataTrails Application. + +#### Primary Image Variables + +- To associate an existing Blob, set the `BLOB_ID`, `BLOB_HASH` value and `BLOB_FILE` from the [Blobs API](/developers/api-reference/blobs-api/): + + {{< note >}} + NOTE: The `ASSET_ID` dependency will be removed with [Non-asset based Events (preview)](/developers/api-reference/events-api/) + {{< /note >}} + + ```bash + ASSET_ID= + BLOB_ID= + BLOB_FILE= + BLOB_HASH= + ``` + + Example: + + ASSET_ID=assets/a1234567-890a + BLOB_ID=blobs/b1234567-890b + BLOB_FILE=conformance.pdf + BLOB_HASH=h1234567hh + +- Associate a Blob as the Event Primary Image: + + ```json + cat > /tmp/event.json < /tmp/event.json < - BLOB_FILE=file.jpg - BLOB_HASH= + BLOB_FILE=cat.jpg + BLOB_HASH= ``` + Example: + + ASSET_ID=assets/a1234567-890a + BLOB_ID=blobs/b1234567-890b + BLOB_FILE=cat.jpg + BLOB_HASH=h1234567h + ```bash cat > /tmp/asset.json <}} -**Note:** This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. -If you are looking for a simple way to test our API you might prefer our [Postman collection](https://www.postman.com/datatrails-inc/workspace/datatrails-public/overview), the [YAML runner](/developers/yaml-reference/story-runner-components/) or the [Developers](https://app.datatrails.io) section of the web UI. +The Attachments API enables attaching and querying Binary Large OBjects (BLOBs) such as documents, process artifacts and images to Assets and Events. -Additional YAML examples can be found in the articles in the [Overview](/platform/overview/introduction/) section. +{{< note >}} +Attachments apply to [Asset-Events](/developers/api-reference/asset-events-api/), and Asset-free [Events](/developers/api-reference/events-api/) (preview). +There are subtle differences that are documented below. {{< /note >}} -The Attachments API enables attaching and querying Binary Large OBjects (BLOBs) such as documents, process artifacts and images to Assets and Events. -Events can also have a primary image associated with the event, providing feedback within the DataTrails application. - -The steps include: +The steps to make an attachment include: 1. Uploading content to the DataTrails [Blobs API](/developers/api-reference/blobs-api/). 1. Attaching the blob to an [Asset](/developers/api-reference/assets-api/) or an [Event](/developers/api-reference/events-api/) 1. Querying the Attachment, through an Asset or an Event -## Attachment API Examples +### Asset-Event Attachments -- Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions. +Assets support attachments by creating an [Asset-Event](/developers/api-reference/asset-events-api/) with nested `arc_` [reserved attributes](/glossary/reserved-attributes/). -- Upload the content of the Attachment using the [Blobs API](/developers/api-reference/blobs-api/). +- `"arc_attribute_type": "arc_attachment"` +- `"arc_blob_identity": "blobs/b1234567-890b"` +- `"arc_blob_hash_alg": "SHA256"` +- `"arc_blob_hash_value": "h1234567h"` +- `"arc_file_name": "conformance.pdf"` +- `"arc_display_name": "Conformance Report"` -### Event Attachments +An example of an Asset-event with two attachments: -- To associate an existing Blob, set the `Asset_ID`, `BLOB_HASH` value and `BLOB_FILE`: +```json + { + "identity": "assets/a1234567-890a/events/e1234567-890e", + "asset_identity": "assets/a1234567-890a", + "event_attributes": { + "arc_description": "Conformance approved for version 1.6", + "arc_display_type": "Conformance Report", + "conformance_report": { + "arc_attribute_type": "arc_attachment", + "arc_blob_identity": "blobs/b1234567-890b", + "arc_blob_hash_alg": "SHA256", + "arc_blob_hash_value": "h1234567h", + "arc_file_name": "conformance.pdf", + "arc_display_name": "Conformance Report" + }, + "security_report": { + "arc_attribute_type": "arc_attachment", + "arc_blob_identity": "blobs/b890123-456b", + "arc_blob_hash_alg": "SHA256", + "arc_blob_hash_value": "h8901234h", + "arc_file_name": "security-report.pdf", + "arc_display_name": "Security Report" + } + }, + "..." + } +``` + +In the above example, the name of the parent attribute (`"conformance_report"`) can be any value, providing a means to name multiple attachments within a single event, such as the additional `"security_report"` attachment. + +The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to reference a DataTrails [Blob](/developers/api-reference/blobs-api/) based attachment. + +## Create an Asset-Event Based Attachment + +- [Create a bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions. +- [Create an Asset](/developers/api-reference/assets-api/) to associate the attachment. +- Upload the content of an Attachment using the [Blobs API](/developers/api-reference/blobs-api/). + +### Asset-Event Attachment Variables + +- To associate an existing Blob, set the `ASSET_ID`, `BLOB_ID`, `BLOB_HASH` value and `BLOB_FILE` from the [Blobs API](/developers/api-reference/blobs-api/): {{< note >}} - NOTE: The `ASSET_ID` dependency will be removed with Non-asset based Events + The `BLOB_HASH` is required, as it creates integrity protection between the content uploaded through the Blobs API, and the integrity protected reference of the Attachment. + Storing the hash in the attachment assures any tampering of the blob storage, including tampering within the DataTrails platform, would be evident. + + When retrieving the blob, the hash retrieved should be compared to the hash of the Attachment API to assure the content has not been tampered with. {{< /note >}} ```bash ASSET_ID= BLOB_ID= - BLOB_FILE=file.jpg BLOB_HASH= + BLOB_FILE=conformance.pdf ``` -### Asset Attachments + Example: + + ASSET_ID=assets/a1234567-890a + BLOB_ID=blobs/b1234567-890b + BLOB_HASH=h1234567h + BLOB_FILE=cat.jpg -Set the `"arc_attribute_type": "arc_attachment"` key-value pair within a dictionary of blob information to add the attachment to the Event. -The name of the attribute (`"conformance_report"` in the following example), can be any value. -The DataTrails platform evaluates `arc_attribute_type` within the attribute properties to understand it references a DataTrails Blob based attachment. +### Create an Asset-Event Attachment -- Create the event payload, referencing the Blob as an integrity protected Attachment: +- Create an event, referencing the Blob as an integrity protected Attachment: ```bash cat > /tmp/event.json < /tmp/event.json < -curl -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v2/attachments/assets/$ASSET_ID/events/$EVENT_ID/$ATTACHMENT_ID -``` + ```bash + ATTACHMENT_ID=$(echo ${BLOB_ID} | cut -d '/' -f 2) -### Retrieve Information About a Specific Attachment + curl -H "@$HOME/.datatrails/bearer-token.txt" \ + --output $BLOB_FILE \ + https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$EVENT_ID/$ATTACHMENT_ID + ``` -It’s also possible to retrieve information about specific attachment using the Attachments API. +### Retrieve Metadata About an Asset-Event Attachment -This information includes the `scanned_status` of the attachment. -Attachment scanning happens in batch, daily. +Metadata information includes the `scanned_status` of the attachment. +Attachment scanning happens daily batches. -To do so, simply issue a request as above with the suffix `/info`. +- Issue a request as above with the suffix `/info`. -```bash -curl -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v2/attachments/assets/$ASSET_ID/$ATTACHMENT_ID/info -``` + ```bash + curl -H "@$HOME/.datatrails/bearer-token.txt" \ + https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$EVENT_ID/$ATTACHMENT_ID/info \ + | jq + ``` The response will include basic information about the attachment: @@ -268,7 +253,7 @@ To integrity protect content located external to the DataTrails platform, exclud ```bash curl -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events/$EVENT_ID \ + https://app.datatrails.ai/archivist/v2/$ASSET_ID/events/$EVENT_ID \ | jq ``` diff --git a/content/developers/api-reference/blobs-api/index.md b/content/developers/api-reference/blobs-api/index.md index 1285fdd56..61ad84d01 100644 --- a/content/developers/api-reference/blobs-api/index.md +++ b/content/developers/api-reference/blobs-api/index.md @@ -14,41 +14,40 @@ toc: true aliases: - /docs/api-reference/blobs-api/ --- -{{< note >}} -**Note:** This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. -If you are looking for a simple way to test our API you might prefer our [Postman collection](https://www.postman.com/datatrails-inc/workspace/datatrails-public/overview), the [YAML runner](/developers/yaml-reference/story-runner-components/) or the [Developers](https://app.datatrails.ai) section of the web UI. - -Additional YAML examples can be found in the articles in the [Overview](/platform/overview/introduction/) section. -{{< /note >}} - -## Blob API Examples - -The Blobs API enables you to upload Binary Large OBjects (BLOBs) such as documents, process artifacts and images to attach to your evidence ledger. +The Blobs API enables uploading Binary Large OBjects (BLOBs) such as documents, process artifacts and images, [attaching](/developers/api-reference/attachments-api/) them to [Assets](/developers/api-reference/assets-api/) and [Events (preview)](/developers/api-reference/events-api/). {{< note >}} -**Note:** Blobs cannot be searched or listed as a collection in their own right: they must always be associated with an Asset or Event through an Attachment Attribute and can only be downloaded by users with appropriate access rights to that Attachment. +**Note:** Blobs cannot be searched or listed as a collection using the blobs resource. +Blobs must be associated with an Asset or Event through an Attachment Attribute and can only be downloaded by users with appropriate access rights to that Attachment. Take note of the Blob ID returned in the API response, it will be needed for use with Assets and Events.
For information on Attachments and how to implement them, please refer to [the Events API Reference](../events-api/#adding-attachments). {{< /note >}} -Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions. +## Blob API Examples -### Upload a Blob +- Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions. -- Download a file, or select another file for upload: +### Reference a Sample File + +An attachment can be any type of file, from media files to code files. +The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any content you desire: + +- Download a picture of Fyodor, or select another file for upload: ```bash curl https://app.datatrails.ai/archivist/v2/attachments/publicassets/208c5282-750e-4302-86f8-eb751de89005/events/4161673f-efa4-4391-bf06-347edd53024e/dae5a430-7d2e-4b88-b753-c09bdcc48c33 \ -o cat.jpg ``` +### Upload a Blob + - Identify the file to upload: ```bash BLOB_FILE=./cat.jpg ``` -- Upload the blob stored at /path/to/file: +- Upload the blob: ```bash curl -X POST \ @@ -65,25 +64,24 @@ Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-u { "hash": { "alg": "SHA256", - "value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + "value": "h1234567h" }, - "identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "identity": "blobs/b123467-890b", "mime_type": "image/jpeg", "size": 21779, - "tenantid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "timestamp_accepted": "2025-01-27T23:45:29Z", - "scanned_status": "NOT_SCANNED", - "scanned_bad_reason": "", - "scanned_timestamp": "" + "tenantid": "t1234567-890t", + "timestamp_accepted": "2025-01-27T23:45:29Z" } ``` ### Retrieve a Blob -- Capture the Blob identity from the above POST: +- Capture the Blob identity from the above POST. + Note, the `` combines `blobs/` and the value. + example:`"identity": "blobs/b123467-890b"` becomes `BLOB_ID=blobs/b123467-890b`: ```bash - BLOB_ID= + BLOB_ID=blobs/ ``` - Retrieve a specific Blob, downloading the `cat.jpg` file: @@ -92,9 +90,16 @@ Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-u curl -H "@$HOME/.datatrails/bearer-token.txt" \ -H "content_type=image/jpg" \ --output "$BLOB_FILE" \ - https://app.datatrails.ai/archivist/v1/blobs/$BLOB_ID + https://app.datatrails.ai/archivist/v1/$BLOB_ID ``` +### Finding Blobs + +The Blobs API does not support a discovery or query API that lists all possible blobs. +Blobs are discovered through their usage within the DataTrails platform, such as the [Attachments API](/developers/api-reference/attachments-api/) or the [Asset Primary Image](/developers/api-reference/assets-api/#primary-image), [Asset-event Primary Image](/developers/api-reference/asset-events-api/#asset-event-primary-image), or the [Event (preview) Primary Image](/developers/api-reference/events-api/#event-primary-image). + +Through the above APIs, capture the value of the `"arc_blob_identity"`, nested below a named attribute with an `"arc_attribute_type": "arc_attachment"`, then use the [Attachments API](/developers/api-reference/attachments-api/) to get metadata about the attachment. + ## Blobs OpenAPI Docs {{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/blobsv1.swagger.json" >}} diff --git a/content/developers/api-reference/events-api/index.md b/content/developers/api-reference/events-api/index.md index 1bd8447b4..e3b8a2107 100644 --- a/content/developers/api-reference/events-api/index.md +++ b/content/developers/api-reference/events-api/index.md @@ -91,6 +91,68 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor } ``` +### DataTrails Reserved Attributes + +### DataTrails Reserved Attributes + +The DataTrails platform has reserved attributes starting with `arc_` to perform specific capabilities. +See [Reserved Attributes](/glossary/reserved-attributes/) for more info. + +### Event Primary Image + +Events can use the [Blobs API](/developers/api-reference/blobs-api/) to associate a primary image in the DataTrails Application. + +#### Primary Image Variables + +- To associate an existing Blob, set the `BLOB_ID`, `BLOB_HASH` value and `BLOB_FILE` from the [Blobs API](/developers/api-reference/blobs-api/): + + ```bash + BLOB_ID= + BLOB_FILE= + BLOB_HASH= + ``` + + Example: + + BLOB_ID=blobs/b1234567-890b + BLOB_FILE=conformance.pdf + BLOB_HASH=h1234567h + +- Associate a Blob as the Event Primary Image: + + ```json + cat > /tmp/event.json <` diff --git a/content/glossary/reserved-attributes/index.md b/content/glossary/reserved-attributes/index.md index dea21e54c..114ff5fab 100644 --- a/content/glossary/reserved-attributes/index.md +++ b/content/glossary/reserved-attributes/index.md @@ -19,25 +19,33 @@ Reserved attributes are asset attributes that are used by the DataTrails platfor Select an attribute to see an example of it in use. -Asset Attributes ----------------- +## Asset Attributes -| **Attribute** | **Meaning** | -|----------------------------|------------------------------------------------------------------| -| [arc_description](/developers/api-reference/assets-api/#asset-record-creation) | brief description of Asset or Event being recorded | -| [arc_display_name](/developers/api-reference/assets-api/#asset-record-creation) | friendly name identifier for Assets, Events, and policies | -| [arc_display_type](/developers/api-reference/assets-api/#asset-record-creation) | classification of the type of Asset being traced that can be used for grouping or access control | -| [arc_home_location_identity](/platform/overview/advanced-concepts/#locations) | physical location to which an Asset nominally 'belongs'. NOT related to the Asset's position in space. For that, use `arc_gis_*` (below) | -| [arc_primary_image](/platform/overview/advanced-concepts/#the-primary-image) | an image attachment that will display as the thumbnail of an Asset | +| **Attribute** | **Meaning** | +|------------------------------------------------------------------------------|--------------| +| [arc_description](/developers/api-reference/assets-api/) | brief description of Asset or Event being recorded | +| [arc_display_name](/developers/api-reference/assets-api/) | friendly name identifier for Assets, Events, and policies | +| [arc_display_type](/developers/api-reference/assets-api/) | classification of the type of Asset being traced that can be used for grouping or access control | +| arc_home_location_identity | physical location to which an Asset nominally 'belongs'. NOT related to the Asset's position in space. For that, use `arc_gis_*` (below) | +| [arc_primary_image](/platform/overview/advanced-concepts/#the-primary-image) | an image attachment that will display as the thumbnail of an Asset | -Event Attributes ----------------- +## Asset-Event Attributes -| **Attribute** | **Meaning** | -|----------------------------|------------------------------------------------------------------| -| [arc_correlation_value](/platform/administration/compliance-policies/#creating-a-compliance-policy) | links Events together for evaluation in Compliance Policies | -| [arc_gis_lat](/platform/overview/advanced-concepts/#locations) | tags the Event as having happened at a particular latitude. Used in the DataTrails UI for mapping | -| [arc_gis_lng](/platform/overview/advanced-concepts/#locations) | tags the Event as having happened at a particular longitude. Used in the DataTrails UI for mapping | -| [arc_description](/developers/api-reference/events-api/#event-creation) | brief description of the Event being recorded | -| [arc_display_type](/developers/api-reference/events-api/#event-creation) | classification of the type of Event being performed that can be used for grouping or access control | -| [arc_primary_image](/platform/overview/advanced-concepts/#the-primary-image) | an image attachment that will display as the thumbnail of the Event | +| **Attribute** | **Meaning** | +|--------------------------------------------------------------------------|-------------| +| [arc_attribute_type](/developers/api-reference/blobs-api/) | When set within a nested attribute, the value of `"arc_attachment"` identifies a reference to a [DataTrails Blob](/developers/api-reference/blobs-api/)
See `arc_blob*` attributes for more info | +| [arc_blob_hash_value](/developers/api-reference/blobs-api/) | When `arc_attribute_type` = `"arc_attachment"`, the value must equal the hash value within the associated `arc_blob_identity`| +| [arc_blob_identity](/developers/api-reference/blobs-api/) | A reference to a [Blob](/developers/api-reference/blobs-api/) | +| [arc_blob_hash_alg](/developers/api-reference/blobs-api/) | The algorithm of the `arc_blob_hash_value` (eg: "SHA256") | +| [arc_correlation_value](/platform/administration/compliance-policies/#creating-a-compliance-policy) | links Events together for evaluation in Compliance Policies | +| [arc_description](/developers/api-reference/asset-events-api/#event-creation) | brief description of the Event being recorded | +| [arc_display_type](/developers/api-reference/asset-events-api/) | classification of the type of Event being performed that can be used for grouping or access control | +| [arc_file_name](/developers/api-reference/blobs-api/) | When `arc_attribute_type` = `"arc_attachment"`, the file name of the blob. | +| [arc_gis_lat](/platform/overview/advanced-concepts/#geolocation) | tags the Event as having happened at a particular latitude. Used in the DataTrails UI for mapping | +| [arc_gis_lng](/platform/overview/advanced-concepts/#geolocation) | tags the Event as having happened at a particular longitude. Used in the DataTrails UI for mapping | +| [arc_primary_image](/developers/api-reference/asset-events-api/#event-primary-image) | an image that displays as the thumbnail of the Event | +| timestamp_declared | a user provided value for when the _Asset Event was declared_.
The value is recorded and integrity protected but not validated as the time is declared outside the scope of DataTrails.
The timestamp_declared can be useful when corelating with `timestamp_accepted` and `timestamp_committed`| +| [document_hash_value](/overview/registering-an-event-against-a-document-profile-asset/) | | +| [document_hash_alg](/overview/registering-an-event-against-a-document-profile-asset/) | | +| [document_version](/overview/registering-an-event-against-a-document-profile-asset/) | | +| [document_status](/overview/registering-an-event-against-a-document-profile-asset/) | | diff --git a/content/platform/overview/advanced-concepts/index.md b/content/platform/overview/advanced-concepts/index.md index c5ad075fb..5ca3d911e 100644 --- a/content/platform/overview/advanced-concepts/index.md +++ b/content/platform/overview/advanced-concepts/index.md @@ -1,7 +1,7 @@ --- title: "Advanced Concepts" description: "DataTrails Advanced Concepts" -lead: "This section goes into more detail on some the subjects covered in Core Concepts, as well as introducing additional advanced topics." +lead: "This section goes into more detail on subjects covered in Core Concepts, introducing some additional concepts." date: 2021-06-14T10:57:58+01:00 lastmod: 2024-03-19T10:57:58+01:00 draft: false @@ -18,11 +18,12 @@ aliases: ## Events The principal objects in the DataTrails platform are *Events*. -These are the records that represent the collective ['Golden Thread'](/platform/overview/core-concepts/#the-golden-thread) of evidence contributed by all stakeholders about a particular thing. +These are the records that represent the collective ['Golden Thread'](/platform/overview/core-concepts/#the-golden-thread) of evidence contributed by all stakeholders about a particular *thing*. -That 'thing' really can represent anything: a file, a piece of data, a physical thing or even a business process. +That *thing* can represent anything: a file, a piece of data, a physical thing or even a business process. +All that's needed is an identifier of the *thing* to corelate across the Events recorded about the *thing*. As long as shared accountability needs to be traced and trustworthy, Events can be recorded about it. -If there are _moments that matter_ they can be committed to the immutable audit log. +If there are *moments that matter* they can be committed to the DataTrails immutable audit log. What defines a moment that matters? It's all about the use case: if you think you might need to prove something in a multi-party dispute later, chances are you can save a lot of time and stress by committing it to the ledger. Simply looking and knowing the current state of things isn't enough: sure, it has software version 3.0 now but when was that released? Before the major incident? After the major incident? This morning before the support call? By recording events into an immutable audit trail, questions relating to that fact can be answered. @@ -50,7 +51,7 @@ This will ensure best performance and minimal code changes to take advantage of Trails will still support simple properties like types, descriptions and thumbnails for search and grouping purposes. {{< /note >}} -In the current platform, Events are registered into collections called _Assets_. +In the current platform, Events are registered into collections called *Assets*. [Assets](/developers/api-reference/assets-api/) may represent an individual thing, a class of things, or something more abstract like 'all Events for this day'. As Assets are retired, Events can still be correlated by Trails or Event Attributes. @@ -64,10 +65,10 @@ An essential value of storing evidence in DataTrails is that data is always avai Given this, it is not possible to actually delete Assets from the system, but there will be cases where it is desirable to hide Assets in the UI or omit them from default searches or compliance queries (for instance as a result of decommissioning or disposal of the corresponding physical asset). To accommodate this need DataTrails separates the Asset estate into 2 classes: tracked Assets (those that are interesting to the system and actively recording events) and untracked Assets (those that are no longer actively interesting). -When for any reason it becomes desirable to remove an Asset, the Asset owner can make it _untracked_ so that it does not appear in lists or searches. +When for any reason it becomes desirable to remove an Asset, the Asset owner can make it *untracked* so that it does not appear in lists or searches. {{< caution >}} -**Caution:** Untracking an Asset does not remove it or its Event history from the system; all stakeholders who previously had access to the record will continue to have access to the Event history, _including_ the untracking event, if they look for it. +**Caution:** Untracking an Asset does not remove it or its Event history from the system; all stakeholders who previously had access to the record will continue to have access to the Event history, *including* the untracking event, if they look for it. {{< /caution >}} ### Timestamps on Events @@ -90,7 +91,7 @@ Having these 3 fields enables users of DataTrails to accurately reflect what is ### User Principals on Events -Just as with the "When", the "Who" of “Who Did What When to an Artifact" is potentially complicated. +Just as with the "When", the "Who" of “Who Did What When to an Artifact" is potentially complicated. For example, an application or gateway may be acting on behalf of some other real-world user. Once committed to the DataTrails system, each lifecycle Event record carries 2 separate user identities: @@ -123,7 +124,7 @@ This one-time manual process helps to underpin trust and security in your DataTr ### Public Attestations While a strict, 1-to-1 relationship might be desirable for some use cases, it is also possible that a recorded asset and associated events are recorded in a more widely accessible way. -With the use of the _Public_ setting for an asset, you can create an access policy which enables anyone to view that asset record. +With the use of the *Public* setting for an asset, you can create an access policy which enables anyone to view that asset record. A viewer of that asset does not have to be registered with DataTrails, and can anonymously use our [Instaproof](/platform/overview/instaproof) service to check the thing they have against the public record in DataTrails. {{< note >}} @@ -234,7 +235,7 @@ A simple Access Policy may look like this: {{< note >}} **Note:** Observe that there are 2 lists in the `filters` which concern different attributes. -The effect of this is to say that an Asset matches the filters if it matches _at least one_ entry from _every list_. +The effect of this is to say that an Asset matches the filters if it matches *at least one* entry from *every list_. Or in other words, inner lists are `OR`, while outer lists are `AND`. For example: @@ -267,7 +268,7 @@ Revoking access can therefore be achieved in a number of ways, any of which may {{< note >}} **Note:** As with any fair decentralized system it is not possible to 'unsee' information. -Any change in OBAC access policies *including revoking OBAC access to a value chain partner* only applies to new information contributed _after_ the policy change. +Any change in OBAC access policies *including revoking OBAC access to a value chain partner* only applies to new information contributed *after* the policy change. This ensures continued fair access to the historic evidence base for all legitimate participants whilst also maintaining control of future operations with the Asset owner. {{< /note >}} @@ -308,7 +309,7 @@ DataTrails supports *GIS coordinates* on Events, which enable recording of exact {{< img src="gis_tracking.png" alt="Rectangle" caption="Tracking Assets with GIS coordinates" class="border-0" >}} -If you're wanting to track the movement of an Asset, or record an audit trail of _where_ a particular Event happens, you can add `arc_gis_lat` and `arc_gis_lng` attributes to the `event_attributes`. +If you're wanting to track the movement of an Asset, or record an audit trail of *where* a particular Event happens, you can add `arc_gis_lat` and `arc_gis_lng` attributes to the `event_attributes`. For example: