DataTrails

Registering a Document Profile Asset

The DataTrails document profile is a set of suggested Asset and Event attributes that allow you to trace the lifecycle of a document.

As it builds on the standard DataTrails asset the same processes are used for Permissioned Sharing and Public Attestation.

The following steps will guide you in creating your first Document Profile Asset.

Check out our Core Concepts for more general information on Assets and Document Profile for details of the Document Profile asset and event attributes.

Registering a Document

  1. Register your Document

    Using the sidebar, select Assets & Documents and then Register Document.

    Registering a Document
    Note: To use the YAML Runner you will need to install the datatrails-archivist python package.

    Click here for installation instructions.

    The DataTrails YAML runner is executed as a series of steps, each step representing a single operation with an `action`.

    In order to create an Asset we use the action ASSETS_CREATE_IF_NOT_EXISTS.

    ---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS

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

    {
  
}

  2. You will see the Document Registration form
    The Document Information tab is where you enter the information that is required by the document profile. You have the option to drag your document into the Auto-fill box or you can enter the information into the form manually.
    The Trust data:

    • Name - This is the unique name of the Document i.e. ‘My First Document’
    • Version - The version of your document
    • SHA-256 Hash - Manually enter the SHA-256 hash of this document version. If you use the auto-fill box we will calculate the SHA-256 hash for you

    Additional options:

    • Upload on Creation - Upload the document in addition to the trust data
    • Attest Publicly - Enable to allow public attestation of the document

      Document Information

      Here you can fill out some more metadata about your asset:

      • selector is the identifying attribute the yaml runner will use to check if your Asset exists already before attempting to create it. In this case, we use arc_display_name which represents the name of the Asset.
      • behaviours detail what class of events in your Asset’s lifecycle you might wish to record; RecordEvidence is the standard and recommended behaviour for all Assets.
      ---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset.
      asset_label: My First Document 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    public: true
    attributes: 
      arc_display_name: My First Document 
      arc_profile: Document
      document_hash_value: ff2f6191ec870e5120a94795274068f520168108cb8fc87f1239ffa72bd2550c
      document_hash_alg: sha256
      document_version: "1"
    confirm: true

      In the file you created earlier, begin adding metadata for your Asset:

      • behaviours detail what class of events in your Asset’s lifecycle you might wish to record; RecordEvidence is the standard and recommended behaviour for all Assets.
      • public determines whether your document is public (true) or private (false)
      {
  "attributes": {
        "arc_display_name": "My First Document",
        "arc_profile": "Document",
        "document_hash_value": "ff2f6191ec870e5120a94795274068f520168108cb8fc87f1239ffa72bd2550c",
        "document_hash_alg":"sha256",
        "document_version":"1"
    },  
   "behaviours": ["RecordEvidence"],
   "public": true
}

  3. The Advanced Options tab is where you enter the Asset Attributes that are required for all asset types and also the optional document profile asset attributes.

    • Document Type - This is the class of the object; while it is arbitrary, it is best to have consistency amongst the type of Documents you use i.e. if it is a purchase order, the type could be Purchase Order, which will then be pre-populated for future Documents to use as their own types.
    • Proof Mechanism - The method used to record the transaction to the DataTrails distributed ledger.

    Please see our Core Concepts section for more information on the Proof Mechanism for your Document

    Advanced Options

    The YAML Runner uses the reserved attributes arc_display_name and arc_display_type to represent Asset Name and Asset Typerespectively.

    ---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset.
      asset_label: My First Document 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    public: true
    attributes: 
      arc_display_name: My First Document 
      arc_profile: Document
      document_hash_value: ff2f6191ec870e5120a94795274068f520168108cb8fc87f1239ffa72bd2550c
      document_hash_alg: sha256
      document_version: "1"
    confirm: true

    The DataTrails API uses the reserved attributes arc_display_name and arc_display_type to represent Asset Name and Asset Typerespectively.

    {
    "attributes": {
        "arc_display_name": "My First Document",
        "arc_profile": "Document",
        "document_hash_value": "ff2f6191ec870e5120a94795274068f520168108cb8fc87f1239ffa72bd2550c",
        "document_hash_alg":"sha256",
        "document_version":"1"

    },
    "behaviours": ["RecordEvidence"],
    "public": true
}

  4. At this point, you may wish to add other details to your Document, including extended attributes or attachments such as PDFs or Thumbnail Images

    Extended attributes are user-defined and can be added to each unique Document.

    Not all Documents of a specific type need to have the same extended attributes, but in most cases it is better to do so for consistency.

    To add a new attribute to a Document, enter your key-value pair.

    For Example:

    Select Add Attribute, and add your key-value pairs

    Document Extended Attributes

    Extended attributes are custom key-value pairs, such as document_version, format, and some_custom_attribute you see below.

    This example also adds a location to our asset. To find out more about locations, click here.

    It’s also good practice to include confirm: true which tells DataTrails to finish committing the Asset before moving to the next step.

    ---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset.
      asset_label: My First Document 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    public: true
    attributes: 
      arc_display_name: My First Document 
      arc_display_type: Promotional Material
      arc_profile: Document
      arc_description: PUBLIC promotional document
      document_hash_value: ff2f6191ec870e5120a94795274068f520168108cb8fc87f1239ffa72bd2550c
      document_hash_alg: sha256
      document_version: "1"
      document_status: Published
      format: pdf
      some_custom_attribute: anything you like
    confirm: true

    Extended attributes are custom key-value pairs, such as document_version, format, and some_custom_attribute you see below.

    This example also adds a location to our Asset. To find out more about locations and how to find your Location ID, click here.

    {
    "attributes": {
        "arc_display_name": "My First Document",
        "arc_display_type": "Promotional Material",
        "arc_profile": "Document",
        "arc_description":"PUBLIC promotional document",
        "document_hash_value": "ff2f6191ec870e5120a94795274068f520168108cb8fc87f1239ffa72bd2550c",
        "document_hash_alg":"sha256",
        "document_version":"1",
        "document_status":"Published",
        "format":"pdf",
        "some_custom_attribute":"anything you like"

    },
    "behaviours": ["RecordEvidence"],
    "public": true
}

  5. Complete your Asset creation

    Click Register Document.

    Register the Document

    Use the archivist_runner command to run your YAML file!

    $ archivist_runner \
      -u https://app.datatrails.ai \
      --client-id <your-client-id> \
      --client-secret client_secret.txt \
      my_first_container.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

  6. View your Document

    Navigate to ‘Assets & Documents’ to see your Asset in the UI.

    Managing Assets

    You can view all Asset data using the ASSETS_LIST action. Use the print_response keyword to get the full output.

    ---
steps:
  - step:
      action: ASSETS_LIST
      description: List all assets.
      print_response: true

    You can view all Asset data using the following command.

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

  7. View details of the Asset you created

    To view your Asset, click on the Asset row. You will see the details and event history of your Asset.

    Viewing Document Asset

    The extended attributes are in the Attributes dropdown.

    The ASSETS_LIST action can be filtered using identifying attributes (attrs) to view the details of a specific Asset.

    ---
steps:An Asset can be anything: a connected machine, a shipping container, or even a data set. It can be any physical or digital object with an associated name, description, and attributes.

Each
  - step:
      action: ASSETS_LIST
      description: Display Asset named My First Document.
      print_response: true
    attrs:
      arc_display_name: My First Document

    Details of a specific asset can be retrieved using identifying attributes (attrs), such as name, type, or presence of a certain field.

    curl -g -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/v2/assets?attributes.arc_display_name=My%20First%20Document

Here we see all details entered: The extended attributes and a history of Events recorded on the Document.

Note: To update the details of your Asset after it has been created, you must create an Event containing Asset Attributes that conform to the Document Profile.

For more information on creating Events, click here.

The first Event in the Event History will always be the Document Registration. In the next section, we will cover how to create your own Events for your Document.

← Creating an Event Against an Asset
Registering an Event Against a Document Profile Asset →