DataTrails

Creating an Event Against an Asset

Creating your first Event

If you wish to begin tracking your Asset history and build an immutable Audit Trail, you need to create Events.

Asset Creation is the first Event. The more Events recorded against an Asset, the richer and deeper its history becomes.

Events track key moments of an Asset’s lifecycle; details of Who Did What When to an Asset.

Note: Before creating an Event, follow this guide to create your first Asset. You will need to wait for the Asset to reach COMMITTED state before attempting to record an Event.

Creating Events

  1. Create an Event

    When viewing your Asset, click the Record Event button.

    Recording an Event
    Note: To use the YAML Runner you will need to install the datatrails-archivist python package.

    Click here for installation instructions.

    To create your Event, use the action EVENTS_CREATE.

    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Record event against My First Container.
      asset_label: assets/<asset-id>
    behaviour: RecordEvidence

    The asset_id must match the Asset ID found in the details of your Asset. See Step 7 of Creating an Asset.

    Create an empty file, in later steps we will add the correct JSON.

    {

}

  2. Add Event type and description

    You will see the following Event creation form:

    Entering Event Details

    Fill out metadata about your Event

    operation and behaviour detail what class of Event is being performed. By default this should always be Record and RecordEvidence, respectively.

    In the attributes section you should also add the required DataTrails attributes arc_description and arc_display_type to represent Event Description and Event Type from the UI.

    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Record event against My First Container.
      asset_label: assets/<asset-id> 
    operation: Record
    behaviour: RecordEvidence
    event_attributes:
      arc_description: Inspection Event
      arc_display_type:  Inspection

    Fill out metadata about your Event; operation and behaviour detail what class of Event is being performed. By default this should always be Record and RecordEvidence, respectively.

    In the attributes section you should also add the required DataTrails attributes arc_description and arc_display_type to represent the UI fields Event Description and Event Type.

    {
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_description": "Inspection Event",
    "arc_display_type": "Inspection",
  }
}

    This Event will be POSTed to a specific Asset endpoint when the curl command is run. To do this, you will need the desired assets/<asset-id> string.


  3. You may enter both Event and Asset attributes

    Event Attributes - Attributes specific to an Event, i.e. which device recorded the Event
    Asset Attributes - Attributes of the Asset that may change as a result of the Event, i.e. overall weight of a container

    Select the Add Attribute button on each tab to add your key-value pairs.
    You may also add an attachment to your Event. In this example we will attach a text document called Inspection Standards as a custom attribute. Select the symbol to upload a file.

    Event Specific Attributes
    Event Asset Attributes

    Add your event_attributes and asset_attributes as key-value pairs. You may also add an attachment to your Event. In this case, we have attached a PDF document labeled Inspection Standards

    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Record event against My First Container.
      asset_label: assets/<asset-id>
    operation: Record
    behaviour: RecordEvidence
    event_attributes:
      arc_description: Inspection Event
      arc_display_type:  Inspection
      Cargo: Rare Metals
    asset_attributes:
      Weight: "1192kg"
    attachments: 
      - filename: inspection_standards.pdf
        content_type: document/pdf
        display_name: Inspection Standards
    confirm: false

    You may add an attachment to your Event. To do so you will need to upload your attachment to DataTrails using the Blobs API.

    curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "content_type=document/pdf" \
    -F "file=@/path/to/file" \
    https://app.datatrails.ai/archivist/v1/blobs

    Add your event_attributes and asset_attributes as key-value pairs. Use the blobs/<attachment-id> returned from the curl command above as the arc_attachment_identity in your Event.

    {
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_description": "Inspection Event",
    "arc_display_type": "Inspection",
    "Cargo": "Rare Metals",
    "inspection_standards": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b",
      "arc_blob_identity": "blobs/<blob-id>",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "standards.pdf",
      "arc_display_name": "Inspection Standards",
      },
  },
  "asset_attributes": {
    "Weight": "1192kg"
  }
}
    Here we see someone noted the type of cargo loaded in the Event, and recorded the total weight of the cargo using a newly defined Weight attribute.

    Every Event has an automatically generated timestamp_accepted and principal_accepted attribute that records when who performed what, as submitted to DataTrails.

    There is an option to append timestamp_declared and principal_declared attributes on the Event, for example, if the Event happened offline or a third party reports it. This creates a more detailed record.

    Documents and images can be recorded with an Event in the same way as an Asset. This is useful for storing additional material that is linked to the Audit Trail metadata for posterity.
    For example, each Inspection Event can store the documentation for the specific standard used for each container inspection. This allows historical checking of Events and the standard and processes that were applied at the time.

  4. Record your Event

    Once you have entered all data, click the Record Event Button to add the Event to your Asset.

    Submitting the Event
    You will see that the Asset Attribute we changed is also recorded in the Asset View.

    Use the archivist_runner to run your YAML file!

    $ archivist_runner \
      -u https://app.datatrails.ai \
      --client-id <your-client-id> \
      --client-secret <your-client-secret> \
      my_first_container_inspection_event.yaml

    Use the curl command to run your JSON file! See instructions for creating your BEARER_TOKEN_FILE here.

    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/<asset-id>/events

  5. View your Event details

    Click the Event history tab and then on a row to inspect the Event:

    Viewing an Event

    Here we see the details entered earlier and also tabs that will show both the Event attributes and Asset attribute updates:

    Viewing Event Attributes
    Viewing Attribute Updates

    The EVENTS_LIST action can be used to view all Events, or filtered using attributes (attrs) to view details of a specific Event

    To view all Events, use:

    ---
steps:
  - step:
      action: EVENTS_LIST
      description: List all events.
      print_response: true

    To view the details of the Event you just created for My First Container, use:

    ---
steps:
  - step:
      action: EVENTS_LIST
      description: List inspection Events against the Asset 'My First Container'.
      print_response: true
      asset_label: assets/<asset-id>
    attrs:
      arc_display_type: Inspection
    asset_attrs:
      arc_display_type: Shipping Container

    Event data can be viewed using curl commands

    To view all Events across all Assets, use:

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

    To view the details of the Event you just created for My First Container, use:

    curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/v2/assets/<asset-id>/events/<event-id>
    Please see the Administration section for information on how to manage your assets

In the next section we look at a specific type of Asset, the Document Profile Asset.

← Creating an Asset
Registering a Document Profile Asset →