Skip to content

Latest commit

 

History

History
480 lines (414 loc) · 15.5 KB

index.md

File metadata and controls

480 lines (414 loc) · 15.5 KB
Raw
title description lead date lastmod draft images menu weight toc aliases
Events API
Events API Reference
Events API Reference
2021-06-09 11:48:40 +0100
2021-06-09 11:48:40 +0100
false
developers
parent
api-reference
107
true
/docs/api-reference/events-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, the YAML runner or the Developers section of the web UI.

Additional YAML examples can be found in the articles in the Overview section. {{< /note >}}

Events API Examples

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

Event Creation

Define the Event parameters and store in /path/to/jsonfile:

{
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "Safety Rating": "90",
    "inspector": "spacetime"
  },
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "principal_declared": {
    "issuer": "idp.synsation.io/1234",
    "subject": "phil.b",
    "email": "phil.b@synsation.io"
  }
}

{{< note >}} Note: RecordEvidence is the primary, default behavior for creating Events. {{< /note >}}

Add the request to the Asset record by POSTing it to the resource:

curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events

The response is:

{
  "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "asset_identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "Safety Rating": "90",
    "inspector": "spacetime"
  },
  "timestamp_accepted": "2019-11-27T15:13:21Z",
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "timestamp_committed": "2019-11-27T15:15:02Z",
  "principal_declared": {
    "issuer": "idp.synsation.io/1234",
    "subject": "phil.b",
    "email": "phil.b@synsation.io"
  },
  "principal_accepted": {
    "issuer": "job.idp.server/1234",
    "subject": "bob@job"
  },
  "confirmation_status": "COMMITTED",
  "block_number": 12,
  "transaction_index": 5,
  "transaction_id": "0x07569"
}

Document Profile Event Creation

There are two Document Profile Events that are available as part of the document lifecycle. These are to publish a new version and to withdraw the document from use.

Publish

Define the Event parameters and store in /path/to/jsonfile:

{
    "behaviour": "RecordEvidence",
    "operation": "Record",
    "asset_attributes": {
        "document_hash_value":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "document_hash_alg":"sha256",
        "document_status": "Published",
        "document_version":"2"
    },
    "event_attributes": {
        "arc_description":"Publish version 2 of Test Document",
        "arc_display_type":"Publish",
        "document_version_authors": [
                        {
                "display_name": "George",
                "email": "george@rainbow.tv"
            },
            {
                "display_name": "Zippy",
                "email": "zippy@rainbow.tv"
            },
            {
                "display_name": "Bungle",
                "email": "bungle@rainbow.tv"
            }
        ]
    }
}

Add the request to the Asset record by POSTing it to the resource:

curl -v -X POST \
    -H "@datatrails-bearer.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events

The response is:

{
    "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "asset_identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "event_attributes": {
        "document_version_authors": [
            {
                "display_name": "George",
                "email": "george@rainbow.tv"
            },
            {
                "display_name": "Zippy",
                "email": "zippy@rainbow.tv"
            },
            {
                "display_name": "Bungle",
                "email": "bungle@rainbow.tv"
            }
        ],
        "arc_description": "Publish version 2 of Test Document",
        "arc_display_type": "Publish"
    },
    "asset_attributes": {
        "document_status": "Published",
        "document_version": "2",
        "document_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "document_hash_alg": "sha256"
    },
    "operation": "Record",
    "behaviour": "RecordEvidence",
    "timestamp_declared": "2023-09-27T12:55:16Z",
    "timestamp_accepted": "2023-09-27T12:55:16Z",
    "timestamp_committed": "1970-01-01T00:00:00Z",
    "principal_declared": {
        "issuer": "https://app.datatrails.ai/appidpv1",
        "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "display_name": "CustomIntegration",
        "email": ""
    },
    "principal_accepted": {
        "issuer": "https://app.datatrails.ai/appidpv1",
        "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "display_name": "CustomIntegration",
        "email": ""
    },
    "confirmation_status": "PENDING",
    "transaction_id": "",
    "block_number": 0,
    "transaction_index": 0,
    "from": "",
    "tenant_identity": ""
}

Withdraw

Define the Event parameters and store in /path/to/jsonfile:

{
    "behaviour": "RecordEvidence",
    "operation": "Record",
    "asset_attributes": {
        "document_status":"Withdrawn"
    },
    "event_attributes": {
        "arc_description":"Withdraw the Test Document",
        "arc_display_type":"Withdraw"
    }
}

Add the request to the Asset record by POSTing it to the resource:

curl -v -X POST \
    -H "@datatrails-bearer.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events

The response is:

{
    "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "asset_identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "event_attributes": {
        "arc_description": "Withdraw the Test Document",
        "arc_display_type": "Withdraw"
    },
    "asset_attributes": {
        "document_status": "Withdrawn"
    },
    "operation": "Record",
    "behaviour": "RecordEvidence",
    "timestamp_declared": "2023-09-27T13:08:32Z",
    "timestamp_accepted": "2023-09-27T13:08:32Z",
    "timestamp_committed": "1970-01-01T00:00:00Z",
    "principal_declared": {
        "issuer": "https://app.datatrails.ai/appidpv1",
        "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "display_name": "CustomIntegration",
        "email": ""
    },
    "principal_accepted": {
        "issuer": "https://app.datatrails.ai/appidpv1",
        "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "display_name": "CustomIntegration",
        "email": ""
    },
    "confirmation_status": "PENDING",
    "transaction_id": "",
    "block_number": 0,
    "transaction_index": 0,
    "from": "",
    "tenant_identity": ""
}

Adding Attachments

The following assumes that an attachment has already been uploaded to DataTrails using the Blob API.

This attachment uuid is generically referred to as:

blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Each attachment has an associated hash value and the name of the hash algorithm used that you can also get from the Blob API response.

Once you've uploaded your file, you can use the "arc_attribute_type": "arc_attachment" key-value pair within a dictionary of blob information to add the attachment to either your Asset or Event.

The following example shows you usage with both the event_attributes and the asset_attributes:

{
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "arc_description": "Safety conformance approved for version 1.6. See attached conformance report",
    "arc_evidence": "DVA Conformance Report attached",
    "conformance_report": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Conformance Report",
    },
    "arc_primary_image": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "photo.jpg",
      "arc_display_name": "arc_primary_image",
    },
  },
  "asset_attributes": {
    "latest_conformance_report": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Latest Conformance Report",
    },
  },
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "principal_declared": {
    "issuer": "idp.synsation.io/1234",
    "subject": "phil.b",
    "email": "phil.b@synsation.io"
  },
}

Add the request to the Asset Record by POSTing it to the resource:

curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events

You should see the response:

{
  "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "asset_identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "arc_description": "Safety conformance approved for version 1.6. See attached conformance report",
    "arc_evidence": "DVA Conformance Report attached",
    "conformance_report": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Conformance Report",
    },
    "arc_primary_image": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Conformance Report",
    },
  },
  "asset_attributes": {
    "latest_conformance_report": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Latest Conformance Report",
    },
  },
  "timestamp_accepted": "2019-11-27T15:13:21Z",
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "timestamp_committed": "2019-11-27T15:15:02Z",
  "principal_declared": {
    "issuer": "idp.synsation.io/1234",
    "subject": "phil.b",
    "email": "phil.b@synsation.io"
  },
  "principal_accepted": {
    "issuer": "job.idp.server/1234",
    "subject": "bob@job"
  },
  "confirmation_status": "COMMITTED",
  "block_number": 12,
  "transaction_index": 5,
  "transaction_id": "0x07569"
}

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:

assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

If you do not know the Event’s identity you can fetch Event records using other information you do know.

Fetch All Events

To fetch all Event records, simply GET the Events resources:

curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/assets/-/events"

Fetch Events for a Specific Asset

If you know the unique identity of the Asset record simply GET the resource:

curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events"

Fetch Specific Events by Identity

If you know the unique identity of the Asset and Event record simply GET the resource:

curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivst/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Fetch Event by Type

To fetch all Events of a specific type, GET the Events resource and filter on arc_display_type:

curl -g -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/assets/-/events?event_attributes.arc_display_type=Software%20Package%20Release"

Fetch 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:

curl -g -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/assets/-/events?asset_attributes.document_status=Published"

Fetch Events by Filtering for Presence of a Field

To fetch all Events with a field set to any value, GET the Events resource and filter on most available fields. For example:

curl -g -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/assets/-/events?event_attributes.arc_display_type=*"

Returns all Events which have arc_display_type that is not empty.

Fetch 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:

curl -g -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/assets/-/events?event_attributes.arc_display_type!=*"

Returns all Events which do not have arc_display_type or in which arc_display_type is empty.

Events OpenAPI Docs

{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/master/doc/assetsv2.swagger.json" >}}