Attachments API

Attachments API Reference

The Attachments API enables attaching and querying Binary Large OBjects (BLOBs) such as documents, process artifacts and images to Assets and Events.

Attachments apply to Asset-Events, and Asset-free Events (preview). There are subtle differences that are documented below.

The steps to make an attachment include:

1. Uploading content to the DataTrails Blobs API.
2. Attaching the blob to an Asset or an Event
3. Querying the Attachment, through an Asset or an Event

Asset-Event Attachments#

Assets support attachments by creating an Asset-Event with nested arc_ reserved attributes.

• "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"

An example of an Asset-event with two attachments:

  {
    "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 based attachment.

Create an Asset-Event Based Attachment#

• Create a bearer_token and store in a file in a secure local directory with 0600 permissions.
• Create an Asset to associate the attachment.
• Upload the content of an Attachment using the 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:

  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.

  ASSET_ID=<asset-id>
  BLOB_ID=<blob-id>
  BLOB_HASH=<hash-value>
  BLOB_FILE=conformance.pdf
  

  Example:

  ASSET_ID=assets/a1234567-890a
  BLOB_ID=blobs/b1234567-890b
  BLOB_HASH=h1234567h
  BLOB_FILE=cat.jpg

Create an Asset-Event Attachment#

• Create an event, referencing the Blob as an integrity protected Attachment:

  cat > /tmp/event.json <<EOF
  {
    "operation": "Record",
    "behaviour": "RecordEvidence",
    "event_attributes": {
      "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": "Fydor"
      }
    }
  }
  EOF
  

• Post to the Asset resource:

  curl -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/tmp/event.json" \
    https://app.datatrails.ai/archivist/v2/$ASSET_ID/events \
    | jq
  

  The response:

  {
    "identity": "assets/a1234567-890a/events/e1234567-890e",
    "asset_identity": "assets/a1234567-890a",
    "event_attributes": {
      "arc_description": "Safety conformance approved for version 1.6.",
      "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": "Fydor"
      },
      "arc_display_type": "Cat-ID"
    },
    "..."
  }
  

Retrieve an Asset-Event Attachment#

• When creating an attachment, an Asset-Event is created. In addition to the Asset_ID captured above, capture the Event_ID

  EVENT_ID=events/e1234567-890e
  

• 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

  ATTACHMENT_ID=$(echo ${BLOB_ID} | cut -d '/' -f 2)
  
  curl -H "@$HOME/.datatrails/bearer-token.txt" \
      --output $BLOB_FILE \
      https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$EVENT_ID/$ATTACHMENT_ID
  

Retrieve Metadata About an Asset-Event Attachment#

Metadata information includes the scanned_status of the attachment. Attachment scanning happens daily batches.

• Issue a request as above with the suffix /info.

  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:

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxx"  },
  "identity": "attachments/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "issuer": "local",
  "mime_type": "image/jpeg",
  "size": 81254,
  "subject": "user@datatrails.ai",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2023-02-06T16:04:31Z",
  "scanned_status": "NOT_SCANNED",
  "scanned_bad_reason": "",
  "scanned_timestamp": ""
}

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.

cat > /tmp/event.json <<EOF
{
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_blob_hash_value": "$BLOB_HASH",
    "arc_blob_hash_alg": "SHA256",
    "arc_file_name": "$BLOB_FILE"
  }
}
EOF

• Post to the Integrity protected content as an Event:

  curl -X POST \
    -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 \
    | jq
  

• Capture the new Event ID from above:

  EVENT_ID=<event-id>
  

• Query the newly created Event, with integrity protection:

  curl -H "@$HOME/.datatrails/bearer-token.txt" \
      https://app.datatrails.ai/archivist/v2/$ASSET_ID/events/$EVENT_ID \
      | jq
  

Attachment OpenAPI Docs#

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"
  },
  "identity": "blobs/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "xxxx@example.com",
  "mime_type": "image/jpeg",
  "scanned_bad_reason": "",
  "scanned_status": "SCANNED_OK",
  "scanned_timestamp": "2019-11-07T15:31:49Z",
  "size": 31424,
  "subject": "user-xxxx@example.com",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2019-11-07T15:31:49Z"
}

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"
  },
  "identity": "blobs/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "xxxx@example.com",
  "mime_type": "image/jpeg",
  "scanned_bad_reason": "",
  "scanned_status": "SCANNED_OK",
  "scanned_timestamp": "2019-11-07T15:31:49Z",
  "size": 31424,
  "subject": "user-xxxx@example.com",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2019-11-07T15:31:49Z"
}

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"
  },
  "identity": "blobs/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "xxxx@example.com",
  "mime_type": "image/jpeg",
  "scanned_bad_reason": "",
  "scanned_status": "SCANNED_OK",
  "scanned_timestamp": "2019-11-07T15:31:49Z",
  "size": 31424,
  "subject": "user-xxxx@example.com",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2019-11-07T15:31:49Z"
}

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"
  },
  "identity": "blobs/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "xxxx@example.com",
  "mime_type": "image/jpeg",
  "scanned_bad_reason": "",
  "scanned_status": "SCANNED_OK",
  "scanned_timestamp": "2019-11-07T15:31:49Z",
  "size": 31424,
  "subject": "user-xxxx@example.com",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2019-11-07T15:31:49Z"
}