DataTrails

Creating an Asset

Creating your first Asset

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 Asset will have a history of any actions performed upon it by any actor.

You may share Assets and their history with specific stakeholders using permission sharing. DataTrails also enables you to publicly attest the provenance of your Assets. To learn how, see Public Attestation.

The creation of an Asset is the first Event in its lifecycle. The following steps will guide you in creating your first Asset.

Check out our Core Concepts for more information on Assets.

Creating an Asset

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

Click here for installation instructions.

  1. Create your Asset

    Using the sidebar, select Register Asset.

    Adding an Asset

    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. Add details to your new Asset and select a Proof Mechanism (currently the only option is Simple Hash)

    Simple Hash commits a batch of events as one blockchain transaction. This allows you to audit if the asset has changed during that time period. Please see our Advanced Concepts section for more information on the Proof Mechanism for your Asset.

    You will see an Asset Creation form, where you provide details of your new Asset:

    Creating an Asset

    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 behavior for all Assets.
    ---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset.
      asset_label: My First Container 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    proof_mechanism: SIMPLE_HASH

    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.
    {
    "behaviours": ["RecordEvidence"],
    "proof_mechanism": "SIMPLE_HASH"
}

  3. At minimum, you will need to add an Asset Name and Asset Type to create an Asset:

    • Asset Name - This is the unique name of the Asset i.e. ‘My First Container’.
    • Asset Type - This is the class of the object; while it is arbitrary, it is best to have consistency amongst the type of Assets you use i.e. if it is a shipping container, the type could be Shipping Container, which will then be pre-populated for future Assets to use as their own types.
      Adding Asset Details

      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 Container 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    proof_mechanism: SIMPLE_HASH
    attributes: 
      arc_display_name: My First Container 
      arc_display_type: Shipping Container

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

      {
    "behaviours": ["RecordEvidence"],
    "proof_mechanism": "SIMPLE_HASH",
    "attributes": {
        "arc_display_name": "My First Container",
        "arc_display_type": "Shipping Container"
    }
}

  4. At this point, you may wish to use the Advanced Options tab to add other details to your Asset, including extended attributes or attachments such as PDFs or Thumbnail Images.

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

    Not all Assets 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 an Asset, enter your key-value pair.

    For Example:

    Select Add Attribute, and add your key-value pairs.

    Asset Extended Attributes

    Extended attributes are custom key-value pairs, such as Width, Length, and Height 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 Container 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    proof_mechanism: SIMPLE_HASH
    attributes: 
      arc_display_name: My First Container 
      arc_display_type: Shipping Container
      arc_description: Originally shipped from Shanghai
      Width: "2.43m"
      Length: "6.06m"
      Height: "2.59m"
    location: 
      selector: 
        - display_name
      display_name: Parkside Junction
      description: Box intersection between Mill Road and East Road
      latitude: 52.2025
      longitude: 0.1311
    confirm: true

    Extended attributes are custom key-value pairs, such as Width, Length, and Height 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.

    {
    "behaviours": ["RecordEvidence"],
    "proof_mechanism": "SIMPLE_HASH",
    "attributes": {
        "arc_display_name": "My First Container",
        "arc_display_type": "Shipping Container",
        "arc_description": "Originally shipped from Shanghai",
        "Width": "2.43m",
        "Length": "6.06m",
        "Height": "2.59m",
        "arc_home_location_identity": "locations/<location-id>",
    }
}

  5. Complete your Asset creation

    Click Register Asset.

    Create the Asset

    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 Assets

    Navigate to ‘Assets’ 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 detailed history of your Asset.

    Viewing an Asset

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

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

    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%20Container
    Here we see all details entered: The extended attributes and a history of Events recorded on the Asset.

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

    For more information on creating Events, click here.

    The first Event will always be the Asset Creation. In the next section, we will cover how to create your own Events for your Asset.

← Advanced Concepts
Creating an Event Against an Asset →