DataTrails

Registering an Event Against a Document Profile Asset

It is rare for a document to remain unchanged during it’s lifetime. Some documents are expected to go though many versions (e.g product documentation) while others (e.g. an employment contract) change much less frequently.

If you need to update your registered Document Profile Asset you can record this as an Event. The Document Profile defines two types of Event; Publish and Withdraw.

Document Registration is the first Event with each new version being recorded as a Publish Event.

There is also the option to record an event (Record Event) that is important but is not formally part of the document profile. An example of this could be a document content review or a change in security classification.

When the document version is no longer to be used there is a Withdraw Event.

These Events track key moments of an Document’s lifecycle; details of Who Did What When to each version of the document.

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

Registering Events

  1. Open the Asset Overview for a Document Profile Asset

    When viewing your Document, you have the choice of Add New Version (publish a new version), Withdraw Document (the document has reached End of Life) or Record Event (any other event that you wish to record).

    Document Asset Overview

    To use the YAML Runner, please visit this link for installation instructions.

    To create your Event, use the action EVENTS_CREATE.

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

    The asset_id must match the Asset ID found in the details of your Document. See Step 7 of Registering a Document Profile Asset.

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

    {

}

    Note: In addition to the Asset and Event attributes that are part of the Document Profile, it is possible to record other attributes that are not part of the profile. These are:

    • Event Attributes - Attributes specific to an Event, i.e. a new author.
    • Asset Attributes - Attributes of the Asset that may change as a result of the Event, i.e. the new document hash.

  2. Adding a New Version

    Click on the Add New Version button.
    Information that is specific to the Document Profile is entered in the Document Information tab. As with registering the document, the new version can be dragged into the auto-fill dropzone or you can manually enter the document hash.

    Document Information
    The Advanced Options tab is for additional Asset and Event attributes that are not part of the document profile.
    Advanced Options

    Add your event_attributes and asset_attributes as key-value pairs.

    Fill out the 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 asset attributes section you should include the required DataTrails asset attributes as defined by the document profile. The new document version hash value is document_hash_value, the hash algorithm is document_hash_alg and the document_status which must be Published.

    In the event attributes section you should also add the required DataTrails event attribute arc_display_type together with any other event specific attributes. The Document Profile specifies that arc_display_type must be Publish.

    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Record event against My First Document.
      asset_label: assets/<asset-id>
    operation: Record
    behaviour: RecordEvidence
    asset_attributes: 
      document_hash_value: 84684c83afd5e9cb3a83439872eae74798979ff5754b15931dbe768092174ec9
      document_hash_alg: sha256
      document_version: "2"
      document_status: Published
    event_attributes:
      arc_description: Publish version 2 of My First Document
      arc_display_type: Publish
      document_version_authors:
        - display_name: Dee Author
          email: dee@writeme.org
        - display_name: Anne Author
          email: anne@writeme.org  
    confirm: false

    Add your event_attributes and asset_attributes as key-value pairs.

    Fill out the 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 asset attributes section you should include the required DataTrails asset attributes as defined by the document profile. The new document version hash value is document_hash_value, the hash algorithm is document_hash_alg and the document_status which must be Published.

    In the event attributes section you should also add the required DataTrails event attribute arc_display_type together with any other event specific attributes. The Document Profile specifies that arc_display_type must be Publish.

    {
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "asset_attributes": {
        "document_hash_value":"84684c83afd5e9cb3a83439872eae74798979ff5754b15931dbe768092174ec9",
        "document_hash_alg":"sha256",
        "document_version":"2",
        "document_status":"Published"
    },
  "event_attributes": {
    "arc_description": "Publish version 2 of My First Document",
    "arc_display_type": "Publish",
          "document_version_authors": [
            {
              "display_name": "Dee Author",
              "email": "dee@writeme.org"
            },
            {
              "display_name": "Anne Author",
              "email": "anne@writeme.org"
            }
          ]  
  }
}

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


  3. The Withdraw Event

    If a document is no longer required, or if for any reason it is decided that it should no longer be used, then a document can be withdrawn.
    Withdrawal is optional and it is usually the final event in the document lifecycle. It can be reversed in DataTrails by publishing a new version.

    Withdraw Event

    Use the attribute/value pairs in the example below to register a Withdraw event

    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Withdraw My First Document.
      asset_label: assets/<asset-id>
    operation: Record
    behaviour: RecordEvidence
    asset_attributes: 
      document_status: Withdrawn
    event_attributes:
      arc_description: Withdraw My First Document
      arc_display_type: Withdraw
    confirm: false

    Use the attribute/value pairs in the example below to register a Withdraw event

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

  4. Recording a Generic Event
    The Record Event button provides a way to record generic events that are not part of the Document Profile lifecycle. The asset and event attributes are in separate tabs in this Event type.

    See Creating an Event Against an Asset for more information on this event type.

    Submitting the Event
    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Record event against My First Document.
      asset_label: assets/<asset-id>
    operation: Record
    behaviour: RecordEvidence
    event_attributes:
      arc_description: Document review
      arc_display_type:  Review
    confirm: false

    {
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_description": "Document Review",
    "arc_display_type": "Review",
  },
}

  5. Registering the Event

    Once your form is complete, click on the Record Event button to register the event.

    Submitting the Event

    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_document_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

  6. Viewing Event details

    The Event History can be seen in the Asset Overview from step 1, simply click on the Event History tab and then any Event row to view it.
    The Overview tab shows the details of the Event including the version and document hash of this specific version.

    Viewing an Event

    The Event attributes and Asset attributes tabs contain any custom attributes that were added when the Event was registered.

    Viewing Event Attributes

    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 Events against the Document 'My First Document'.
      print_response: true
      asset_label: assets/59e2b78b-d555-49a0-8775-f336b640122e 
    attrs:
      arc_display_type: Publish

    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 Document, use:

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

← Registering a Document Profile Asset
Instaproof →