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.
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.
{ }
Add details to your new Asset and select a
Proof Mechanism
(currently the only option isSimple 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 usearc_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" }
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 beShipping 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
andarc_display_type
to representAsset Name
andAsset Type
respectively.--- 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
andarc_display_type
to representAsset Name
andAsset Type
respectively.{ "behaviours": ["RecordEvidence"], "proof_mechanism": "SIMPLE_HASH", "attributes": { "arc_display_name": "My First Container", "arc_display_type": "Shipping Container" } }
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
, andHeight
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
, andHeight
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>", } }
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
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 theprint_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
View details of the Asset you created
Here we see all details entered: The extended attributes and a history of Events recorded on the Asset.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
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.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.