From 5c624a8effe40215636957b15bc81bbaf264fd65 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Mon, 3 Feb 2025 16:22:13 -0800 Subject: [PATCH 1/9] Attachment updates Signed-off-by: steve lasker --- .../api-reference/asset-events-api/index.md | 185 +++++++----------- .../api-reference/assets-api/index.md | 13 +- .../api-reference/attachments-api/index.md | 152 ++++++-------- .../api-reference/blobs-api/index.md | 46 +++-- .../api-reference/events-api/index.md | 69 +++++++ 5 files changed, 251 insertions(+), 214 deletions(-) diff --git a/content/developers/api-reference/asset-events-api/index.md b/content/developers/api-reference/asset-events-api/index.md index 80b21289e..cee6aa068 100644 --- a/content/developers/api-reference/asset-events-api/index.md +++ b/content/developers/api-reference/asset-events-api/index.md @@ -136,6 +136,82 @@ 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 as reserved attributes starting with `arc_`. +Asset-Events have the following reserved attributes: + +- **`arc_display_type`**: The value used to display in the DataTrails Application. +- **`arc_primary_image`**: A attribute containing a dictionary of references to a Blob, used to display in the DataTrails Application. +- **`arc_attribute_type`**: When set within a nested attribute, the value of `"arc_attachment"` identifies a reference to a [DataTrails Blob](/developers/api-reference/blobs-api/) +- **`arc_display_name"`**: When set to `"arc_primary_image"`, the blob is displayed in the DataTrails application. +- **`arc_blob_hash_value`**: When `arc_attribute_type` = `"arc_attachment"`, the value must equal the hash value within the associated `arc_blob_identity`. +- **`arc_blob_identity`**: A reference to a [Blob](/developers/api-reference/blobs-api/) +- **`arc_blob_hash_alg`**: The algorithm of the `arc_blob_hash_value` (eg: "SHA256") +- **`arc_file_name`**: When `arc_attribute_type` = `"arc_attachment"`, the file name of the blob. + +### 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-8901 + BLOB_ID=blobs/b1234567-8901 + BLOB_FILE=conformance.pdf + BLOB_HASH=h1234567 + +- 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-8901 + BLOB_ID=blobs/b1234567-8901 + BLOB_FILE=cat.jpg + BLOB_HASH=h1234567 + ```bash cat > /tmp/asset.json <}} - NOTE: The `ASSET_ID` dependency will be removed with Non-asset based Events + 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=file.jpg + BLOB_FILE= BLOB_HASH= ``` -### Asset Attachments + Example: -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. + ASSET_ID=assets/a1234567-8901 + BLOB_ID=blobs/b1234567-8901 + BLOB_FILE=conformance.pdf + BLOB_HASH=h1234567 -- Create the event payload, referencing the Blob as an integrity protected Attachment: +### Create an Asset-Event Attachment + +- Create an event, referencing the Blob as an integrity protected Attachment: ```bash cat > /tmp/event.json < /tmp/event.json <` combines `blobs/` and the ID + example:`"identity": "blobs/b123467-8901"` becomes `BLOB_ID=blobs/b123467-8901`: ```bash BLOB_ID= @@ -92,9 +96,29 @@ 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 primary image of an Asset or Event. +Through the Attachments API, capture the value of the `"arc_blob_identity"`, nested below a named attribute with an `"arc_attribute_type": "arc_attachment"`: + +```json +{ + "event_attributes": { + "conformance_report": { + "arc_attribute_type": "arc_attachment", + "arc_blob_identity": "blobs/b123456-7890", + "arc_blob_hash_value": "h123456", + "arc_blob_hash_alg": "SHA256", + "arc_file_name": "Conformance.pdf" + } + } +} +``` + ## 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..7c2902c14 100644 --- a/content/developers/api-reference/events-api/index.md +++ b/content/developers/api-reference/events-api/index.md @@ -91,6 +91,75 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor } ``` +### DataTrails Reserved Attributes + +The DataTrails platform as reserved attributes starting with `arc_`. +Asset-Events have the following reserved attributes: + +- **`arc_display_type`**: The value used to display in the DataTrails Application. +- **`arc_primary_image`**: A attribute containing a dictionary of references to a Blob, used to display in the DataTrails Application. +- **`arc_attribute_type`**: When set within a nested attribute, the value of `"arc_attachment"` identifies a reference to a [DataTrails Blob](/developers/api-reference/blobs-api/) +- **`arc_display_name"`**: When set to `"arc_primary_image"`, the blob is displayed in the DataTrails application. +- **`arc_blob_hash_value`**: When `arc_attribute_type` = `"arc_attachment"`, the value must equal the hash value within the associated `arc_blob_identity`. +- **`arc_blob_identity`**: A reference to a [Blob](/developers/api-reference/blobs-api/) +- **`arc_blob_hash_alg`**: The algorithm of the `arc_blob_hash_value` (eg: "SHA256") +- **`arc_file_name`**: When `arc_attribute_type` = `"arc_attachment"`, the file name of the blob. + +### 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-8901 + BLOB_FILE=conformance.pdf + BLOB_HASH=h1234567 + +- Associate a Blob as the Event Primary Image: + + ```json + cat > /tmp/event.json <` From 00982ecc6b38914392798b70049f1fc942f2de92 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Mon, 3 Feb 2025 16:25:07 -0800 Subject: [PATCH 2/9] Attempt to make GitHub review UX happy with json snippets Signed-off-by: steve lasker --- content/developers/api-reference/attachments-api/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index 390a64b9b..117fd6f0d 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -146,8 +146,7 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re "arc_display_name": "Conformance Report" }, "arc_display_type": "Safety Conformance" - }, - ... + } ``` ### Retrieve a Specific Attachment on an Asset From 1cd754b748edd50578702eacafbf524fdbcda76c Mon Sep 17 00:00:00 2001 From: steve lasker Date: Mon, 3 Feb 2025 16:26:18 -0800 Subject: [PATCH 3/9] Attempt to make GitHub review UX happy with json snippets Signed-off-by: steve lasker --- content/developers/api-reference/attachments-api/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index 117fd6f0d..7325326eb 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -58,8 +58,7 @@ For example: "arc_file_name": "conformance.pdf", "arc_display_name": "Conformance Report" } - }, - ... + } ``` The name of the parent attribute (`"conformance_report"`) can be any value, providing a means to name multiple attachments within a single event. From cb811bf9038fc1cff22c54fd9e42d7ff696269c3 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Mon, 3 Feb 2025 16:26:58 -0800 Subject: [PATCH 4/9] Attempt to make GitHub review UX happy with json snippets Signed-off-by: steve lasker --- content/developers/api-reference/attachments-api/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index 7325326eb..90083fbfe 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -58,7 +58,9 @@ For example: "arc_file_name": "conformance.pdf", "arc_display_name": "Conformance Report" } - } + }, + "..." + } ``` The name of the parent attribute (`"conformance_report"`) can be any value, providing a means to name multiple attachments within a single event. From fbb569c8770be852b726641998d54ab8f7eddaa2 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Thu, 6 Feb 2025 14:32:23 -0800 Subject: [PATCH 5/9] Additional, incremental progress on attachments Signed-off-by: steve lasker --- .../api-reference/asset-events-api/index.md | 73 ++++++++----------- .../api-reference/assets-api/index.md | 6 +- .../api-reference/attachments-api/index.md | 36 +++++---- .../api-reference/events-api/index.md | 19 ++--- content/glossary/reserved-attributes/index.md | 46 +++++++----- .../overview/advanced-concepts/index.md | 25 ++++--- 6 files changed, 103 insertions(+), 102 deletions(-) diff --git a/content/developers/api-reference/asset-events-api/index.md b/content/developers/api-reference/asset-events-api/index.md index cee6aa068..0258e206d 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 ``` @@ -138,17 +138,8 @@ In a future release, Events will be created independently from Assets. ### DataTrails Reserved Attributes -The DataTrails platform as reserved attributes starting with `arc_`. -Asset-Events have the following reserved attributes: - -- **`arc_display_type`**: The value used to display in the DataTrails Application. -- **`arc_primary_image`**: A attribute containing a dictionary of references to a Blob, used to display in the DataTrails Application. -- **`arc_attribute_type`**: When set within a nested attribute, the value of `"arc_attachment"` identifies a reference to a [DataTrails Blob](/developers/api-reference/blobs-api/) -- **`arc_display_name"`**: When set to `"arc_primary_image"`, the blob is displayed in the DataTrails application. -- **`arc_blob_hash_value`**: When `arc_attribute_type` = `"arc_attachment"`, the value must equal the hash value within the associated `arc_blob_identity`. -- **`arc_blob_identity`**: A reference to a [Blob](/developers/api-reference/blobs-api/) -- **`arc_blob_hash_alg`**: The algorithm of the `arc_blob_hash_value` (eg: "SHA256") -- **`arc_file_name`**: When `arc_attribute_type` = `"arc_attachment"`, the file name of the blob. +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 @@ -171,10 +162,10 @@ Asset-Events can use the [Blobs API](/developers/api-reference/blobs-api/) to as Example: - ASSET_ID=assets/a1234567-8901 - BLOB_ID=blobs/b1234567-8901 + ASSET_ID=assets/a1234567-890a + BLOB_ID=blobs/b1234567-890b BLOB_FILE=conformance.pdf - BLOB_HASH=h1234567 + BLOB_HASH=h1234567hh - Associate a Blob as the Event Primary Image: @@ -187,9 +178,9 @@ Asset-Events can use the [Blobs API](/developers/api-reference/blobs-api/) to as "arc_primary_image": { "arc_attribute_type": "arc_attachment", "arc_display_name": "arc_primary_image", - "arc_blob_hash_value": "$BLOB_HASH", "arc_blob_identity": "$BLOB_ID", "arc_blob_hash_alg": "SHA256", + "arc_blob_hash_value": "$BLOB_HASH", "arc_file_name": "$BLOB_FILE" } } @@ -204,7 +195,7 @@ Asset-Events can use the [Blobs API](/developers/api-reference/blobs-api/) to as -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 ``` @@ -260,7 +251,7 @@ There are two [Document Profile Events](/developers/developer-patterns/document- -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 ``` @@ -347,7 +338,7 @@ There are two [Document Profile Events](/developers/developer-patterns/document- -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 ``` @@ -390,19 +381,19 @@ There are two [Document Profile Events](/developers/developer-patterns/document- } ``` -### Event Record Retrieval +## Asset Event Record Retrieval -Event records in DataTrails are tokenized at creation time and referred to in all future API calls by a permanent unique identity of the form: +Asset Event records in DataTrails are tokenized at creation time and referred to in all future API calls by a permanent unique identity of the form: ```bash -assets/$ASSET_ID/events/$EVENT_ID +assets/a1234567-890a/events/$EVENT_ID ``` If you do not know the Event’s identity you can fetch Event records using other information you do know. -#### Fetch All Events +### Fetch All Asset Events -- To fetch all Event records, simply `GET` the Events resources: +- To fetch all Asset Event records, simply `GET` the Events resources: ```bash curl -X GET \ @@ -411,31 +402,31 @@ If you do not know the Event’s identity you can fetch Event records using othe | jq ``` -#### Fetch Events for a Specific Asset +### Fetch Asset Events for a Specific Asset - If you know the unique identity of the Asset record simply `GET` the resource: ```bash curl -X GET \ -H "@$HOME/.datatrails/bearer-token.txt" \ - "https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events?page_size=5" \ + "https://app.datatrails.ai/archivist/v2/$ASSET_ID/events?page_size=5" \ | jq ``` -#### Fetch Specific Events by Identity +### Fetch Specific Asset Events by Identity - If you know the unique identity of the Asset and Event record simply `GET` the resource: ```bash curl -X GET \ -H "@$HOME/.datatrails/bearer-token.txt" \ - "https://app.datatrails.ai/archivst/v2/assets/$ASSET_ID/events/$EVENT_ID" \ + "https://app.datatrails.ai/archivst/v2/$ASSET_ID/events/$EVENT_ID" \ | jq ``` -#### Fetch Event by Type +### Fetch Asset Event by Type -- To fetch all Events of a specific type, `GET` the Events resource and filter on `arc_display_type`: +- To fetch all Asset Events of a specific type, `GET` the Events resource and filter on `arc_display_type`: ```bash curl -g -X GET \ @@ -444,9 +435,9 @@ If you do not know the Event’s identity you can fetch Event records using othe | jq ``` -#### Fetch Event by Asset Attribute +### Fetch Asset Event by Asset Attribute -- To fetch all Events of a specific Asset attribute, `GET` the Events resource and filter on `asset_attributes` at the Asset level: +- To fetch all Asset Events of a specific Asset attribute, `GET` the Events resource and filter on `asset_attributes` at the Asset level: ```bash curl -g -X GET \ @@ -455,9 +446,9 @@ If you do not know the Event’s identity you can fetch Event records using othe | jq ``` -#### Fetch Events by Filtering for Presence of a Field +### Fetch Asset Events by Filtering for Presence of an Attribute -- To fetch all Events with a field set to any value, `GET` the Events resource and filter on most available fields. For example: +- To fetch all Asset Events with an Attribute set to any value, `GET` the Asset-Events resource and filter on most available attributes. ```bash curl -g -X GET \ @@ -468,9 +459,9 @@ If you do not know the Event’s identity you can fetch Event records using othe Returns all Events which have `arc_display_type` that is not empty. -#### Fetch Events Which are Missing a Field +### Fetch Asset Events Which are Missing a Field -- To fetch all Events with a field which is not set to any value, `GET` the Events resource and filter on most available fields. For example: +- To fetch all Asset Events with a field which is not set to any value, `GET` the Events resource and filter on most available fields. ```bash curl -g -X GET \ @@ -479,11 +470,11 @@ If you do not know the Event’s identity you can fetch Event records using othe | jq ``` - Returns all Events which do not have `arc_display_type` or in which `arc_display_type` is empty. + Returns all Asset Events which do not have `arc_display_type` or in which `arc_display_type` is empty. -#### Fetch Events by Minimum Confirmation Status +### Fetch Asset Events by Minimum Confirmation Status -- To fetch all Events with a specified confirmation status or higher, `GET` the Events resource and filter on `minimum_trust`. +- To fetch all Asset Events with a specified confirmation status or higher, `GET` the Events resource and filter on `minimum_trust`. ```bash curl -g -X GET \ @@ -492,7 +483,7 @@ If you do not know the Event’s identity you can fetch Event records using othe | jq ``` -- To fetch all Events which have a `confirmation_status` level of COMMITTED, CONFIRMED or UNEQUIVOCAL. +- To fetch all Asset Events which have a `confirmation_status` level of COMMITTED, CONFIRMED or UNEQUIVOCAL. ```bash curl -g -X GET \ @@ -501,7 +492,7 @@ If you do not know the Event’s identity you can fetch Event records using othe | jq ``` - Returns all Events which have a `confirmation_status` level of CONFIRMED or UNEQUIVOCAL. + Returns all Asset Events which have a `confirmation_status` level of CONFIRMED or UNEQUIVOCAL. ## Events OpenAPI Docs diff --git a/content/developers/api-reference/assets-api/index.md b/content/developers/api-reference/assets-api/index.md index d439992c0..74baf0dc4 100644 --- a/content/developers/api-reference/assets-api/index.md +++ b/content/developers/api-reference/assets-api/index.md @@ -108,10 +108,10 @@ The image must first be uploaded with the [Blobs API](/developers/api-reference/ Example: - ASSET_ID=assets/a1234567-8901 - BLOB_ID=blobs/b1234567-8901 + ASSET_ID=assets/a1234567-890a + BLOB_ID=blobs/b1234567-890b BLOB_FILE=cat.jpg - BLOB_HASH=h1234567 + BLOB_HASH=h1234567h ```bash cat > /tmp/asset.json <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: From 5e9837936c7835764d6a42bcdc1a4177c4059259 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Fri, 7 Feb 2025 17:06:44 -0800 Subject: [PATCH 6/9] Attachment Updates Signed-off-by: steve lasker --- .../api-reference/asset-events-api/index.md | 2 +- .../api-reference/assets-api/index.md | 2 +- .../api-reference/attachments-api/index.md | 41 +++++++------- .../api-reference/blobs-api/index.md | 53 ++++++------------- 4 files changed, 41 insertions(+), 57 deletions(-) diff --git a/content/developers/api-reference/asset-events-api/index.md b/content/developers/api-reference/asset-events-api/index.md index 0258e206d..02048d29f 100644 --- a/content/developers/api-reference/asset-events-api/index.md +++ b/content/developers/api-reference/asset-events-api/index.md @@ -141,7 +141,7 @@ In a future release, Events will be created independently from Assets. 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 +### 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. diff --git a/content/developers/api-reference/assets-api/index.md b/content/developers/api-reference/assets-api/index.md index 74baf0dc4..bf711ea03 100644 --- a/content/developers/api-reference/assets-api/index.md +++ b/content/developers/api-reference/assets-api/index.md @@ -93,7 +93,7 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor } ``` -### Assets With a Primary Image +### Primary Image An Asset can have a primary image, displayed in the DataTrails Application. The image must first be uploaded with the [Blobs API](/developers/api-reference/blobs-api/), with the BLOB_ID, BLOB_HASH and BLOB_FILE captured for uploading the asset. diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index bf999ca72..0aa0cc5f4 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -14,17 +14,14 @@ toc: true aliases: - /docs/api-reference/attachments-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.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/) @@ -32,7 +29,7 @@ The steps include: ### Asset-Event Attachments -Assets support attachments by creating an [Asset-Event](/developers/api-reference/asset-events-api/) with nested `arc_` [Reserved Attributes](/glossary/reserved-attributes/). +Assets support attachments by creating an [Asset-Event](/developers/api-reference/asset-events-api/) with nested `arc_` [reserved attributes](/glossary/reserved-attributes/). - `"arc_attribute_type": "arc_attachment"` - `"arc_blob_identity": "blobs/b1234567-890b"` @@ -41,7 +38,7 @@ Assets support attachments by creating an [Asset-Event](/developers/api-referenc - `"arc_file_name": "conformance.pdf"` - `"arc_display_name": "Conformance Report"` -For example: +Example of an Asset-event with two attachments: ```json { @@ -71,36 +68,40 @@ For example: } ``` -The name of the parent attribute (`"conformance_report"`) can be any value, providing a means to name multiple attachments within a single event. -The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to reference a DataTrails Blob based attachment. +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. -## Attachment API Examples +The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to reference a DataTrails [Blob](/developers/api-reference/blobs-api/) based attachment. + +## Asset-Event Attachment API Examples - 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. - Upload the content of the Attachment using the [Blobs API](/developers/api-reference/blobs-api/). -### Attachment Variables +### 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 (preview)](/developers/api-reference/events-api/) + 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= BLOB_HASH= + BLOB_FILE=conformance.pdf ``` Example: ASSET_ID=assets/a1234567-890a BLOB_ID=blobs/b1234567-890b - BLOB_FILE=conformance.pdf BLOB_HASH=h1234567h + BLOB_FILE=conformance.pdf ### Create an Asset-Event Attachment @@ -155,14 +156,16 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re "arc_display_name": "Conformance Report" }, "arc_display_type": "Safety Conformance" - } + }, + "..." + } ``` ### Retrieve a Specific Attachment on an Asset ```bash curl -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v2/attachments/assets/$ASSET_ID/$ATTACHMENT_ID + https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$ATTACHMENT_ID ``` ### Retrieve a Specific Attachment on an Event diff --git a/content/developers/api-reference/blobs-api/index.md b/content/developers/api-reference/blobs-api/index.md index 623a2d0f9..5014c50e2 100644 --- a/content/developers/api-reference/blobs-api/index.md +++ b/content/developers/api-reference/blobs-api/index.md @@ -14,26 +14,20 @@ 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 + +- 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. -### Sample Attachment +### 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: @@ -53,7 +47,7 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c BLOB_FILE=./cat.jpg ``` -- Upload the blob stored at /path/to/file: +- Upload the blob: ```bash curl -X POST \ @@ -70,12 +64,12 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c { "hash": { "alg": "SHA256", - "value": "h123456" + "value": "h1234567h" }, - "identity": "blobs/b123467-8901", + "identity": "blobs/b123467-890b", "mime_type": "image/jpeg", "size": 21779, - "tenantid": "t1234567-8901-xxxx-xxxx-xxxxxxxxxxxx", + "tenantid": "t1234567-890t", "timestamp_accepted": "2025-01-27T23:45:29Z" } ``` @@ -83,11 +77,11 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c ### Retrieve a Blob - Capture the Blob identity from the above POST. - Note, the `` combines `blobs/` and the ID - example:`"identity": "blobs/b123467-8901"` becomes `BLOB_ID=blobs/b123467-8901`: + 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: @@ -102,22 +96,9 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c ### 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 primary image of an Asset or Event. -Through the Attachments API, capture the value of the `"arc_blob_identity"`, nested below a named attribute with an `"arc_attribute_type": "arc_attachment"`: - -```json -{ - "event_attributes": { - "conformance_report": { - "arc_attribute_type": "arc_attachment", - "arc_blob_identity": "blobs/b123456-7890", - "arc_blob_hash_value": "h123456", - "arc_blob_hash_alg": "SHA256", - "arc_file_name": "Conformance.pdf" - } - } -} -``` +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 From 2554fcad6813315517854563e57b498dd764956c Mon Sep 17 00:00:00 2001 From: steve lasker Date: Thu, 20 Feb 2025 14:40:02 -0800 Subject: [PATCH 7/9] replace attachment_id with blob_id Signed-off-by: steve lasker --- content/developers/api-reference/attachments-api/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index 0aa0cc5f4..4e479ffa7 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -165,7 +165,8 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re ```bash curl -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$ATTACHMENT_ID + --output $BLOB_FILE + https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$BLOB_ID ``` ### Retrieve a Specific Attachment on an Event From 79b1d9db45441c638335035ee3fd451f6c732a45 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Fri, 21 Feb 2025 14:10:58 -0800 Subject: [PATCH 8/9] Update attachments with functional code Signed-off-by: steve lasker --- .../api-reference/attachments-api/index.md | 116 ++++++------------ .../api-reference/blobs-api/index.md | 2 +- 2 files changed, 39 insertions(+), 79 deletions(-) diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index 4e479ffa7..81601f5b9 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -38,7 +38,7 @@ Assets support attachments by creating an [Asset-Event](/developers/api-referenc - `"arc_file_name": "conformance.pdf"` - `"arc_display_name": "Conformance Report"` -Example of an Asset-event with two attachments: +An example of an Asset-event with two attachments: ```json { @@ -68,15 +68,15 @@ Example of an Asset-event with two attachments: } ``` -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. +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. -## Asset-Event Attachment API Examples +## Create an Asset-Event Based Attachment -- 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. - -- Upload the content of the Attachment using the [Blobs API](/developers/api-reference/blobs-api/). +- [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 @@ -101,7 +101,7 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re ASSET_ID=assets/a1234567-890a BLOB_ID=blobs/b1234567-890b BLOB_HASH=h1234567h - BLOB_FILE=conformance.pdf + BLOB_FILE=cat.jpg ### Create an Asset-Event Attachment @@ -113,15 +113,15 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re "operation": "Record", "behaviour": "RecordEvidence", "event_attributes": { - "arc_display_type": "Safety Conformance", - "arc_description": "Safety conformance approved for version 1.6.", - "conformance_report": { + "arc_display_type": "Cat-ID", + "arc_description": "Fydor, the cat on the scene", + "cat-id": { "arc_attribute_type": "arc_attachment", "arc_blob_hash_value": "$BLOB_HASH", "arc_blob_identity": "$BLOB_ID", "arc_blob_hash_alg": "SHA256", "arc_file_name": "$BLOB_FILE", - "arc_display_name": "Conformance Report" + "arc_display_name": "Fydor" } } } @@ -147,49 +147,52 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re "asset_identity": "assets/a1234567-890a", "event_attributes": { "arc_description": "Safety conformance approved for version 1.6.", - "conformance_report": { + "cat-id": { "arc_attribute_type": "arc_attachment", "arc_blob_hash_value": "h1234567h", "arc_blob_identity": "blobs/b1234567-890b", "arc_blob_hash_alg": "SHA256", "arc_file_name": "cat.jpg", - "arc_display_name": "Conformance Report" + "arc_display_name": "Fydor" }, - "arc_display_type": "Safety Conformance" + "arc_display_type": "Cat-ID" }, "..." } ``` -### Retrieve a Specific Attachment on an Asset +### Retrieve an Asset-Event Attachment -```bash -curl -H "@$HOME/.datatrails/bearer-token.txt" \ - --output $BLOB_FILE - https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$BLOB_ID -``` +- When creating an attachment, an Asset-Event is created. + In addition to the Asset_ID captured above, capture the Event_ID + + ```bash + EVENT_ID=events/e1234567-890e + ``` -### Retrieve a Specific Attachment on an Event +- The `attachments/assets` Resource does not support `/blobs/` as part of the resource identifier. + The `ATTACHMENT_ID` variable will parse the ID from the `$BLOB_ID` -```bash -ASSET_ID= -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: @@ -211,49 +214,6 @@ The response will include basic information about the attachment: } ``` -### Integrity Protecting External Content - -To integrity protect content located external to the DataTrails platform, exclude the `"arc_attribute_type": "arc_attachment"`, `"arc_blob_identity"` and `"arc_display_name"` as not being relevant to external content. - - ```json - cat > /tmp/event.json < - ``` - -- Query the newly created Event, with integrity protection: - - ```bash - curl -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events/$EVENT_ID \ - | jq - ``` - ## Attachment OpenAPI Docs {{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/attachmentsv2.swagger.json" >}} diff --git a/content/developers/api-reference/blobs-api/index.md b/content/developers/api-reference/blobs-api/index.md index 5014c50e2..61ad84d01 100644 --- a/content/developers/api-reference/blobs-api/index.md +++ b/content/developers/api-reference/blobs-api/index.md @@ -18,7 +18,7 @@ The Blobs API enables uploading Binary Large OBjects (BLOBs) such as documents, {{< note >}} **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. +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 >}} From f5d9aee3d7b1eeb030ae452eea48a5338d78f60a Mon Sep 17 00:00:00 2001 From: steve lasker Date: Wed, 26 Mar 2025 22:07:27 +0200 Subject: [PATCH 9/9] Add integrity protecting external content Signed-off-by: steve lasker --- .../api-reference/attachments-api/index.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/content/developers/api-reference/attachments-api/index.md b/content/developers/api-reference/attachments-api/index.md index 81601f5b9..4d1e6ca10 100644 --- a/content/developers/api-reference/attachments-api/index.md +++ b/content/developers/api-reference/attachments-api/index.md @@ -214,6 +214,49 @@ The response will include basic information about the attachment: } ``` +### Integrity Protecting External Content + +To integrity protect content located external to the DataTrails platform, exclude the `"arc_attribute_type": "arc_attachment"`, `"arc_blob_identity"` and `"arc_display_name"` as not being relevant to external content. + + ```json + cat > /tmp/event.json < + ``` + +- Query the newly created Event, with integrity protection: + + ```bash + curl -H "@$HOME/.datatrails/bearer-token.txt" \ + https://app.datatrails.ai/archivist/v2/$ASSET_ID/events/$EVENT_ID \ + | jq + ``` + ## Attachment OpenAPI Docs {{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/attachmentsv2.swagger.json" >}}