DataTrails

Grouping Assets by Location

Adding a Location

Locations associate an Asset with a ‘home’ that can help when governing sharing policies with OBAC and ABAC. Locations do not need pinpoint precision and can be named by site, building, or other logical grouping.

It may be useful to indicate an Asset’s origin. For example, if tracking traveling consultant’s laptops, you may wish to associate them with a ‘home’ office.

Caution: It is important to recognize that the location does not necessarily denote the Asset’s current position in space; it simply determines which facility the Asset belongs to. For things that move around, use GIS coordinates on Events instead. See concept docs on locations for more information.

Creating a Location

Note: The Locations UI is not displayed in the side menu until after the first location has been created using the API. After this you can use the UI to create new locations but to update or delete a location you will still need to use the API

  1. Create your location

    In the dashboard, select Locations, then Add Location.

    Adding a Location

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

    In order to create a location, we use the action LOCATIONS_CREATE_IF_NOT_EXISTS.

    ---
steps:
  - step:
      action: LOCATIONS_CREATE_IF_NOT_EXISTS

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

    {

}

  2. Add information about the location you are creating

    The following screen will appear:

    The Location Webform

    You may add a description and a selector. The selector is the identifying attribute used to check if your location exists before attempting to create it. In this case, we use display_name which represents the name of the location.

    ---
steps:
  - step:
      action: LOCATIONS_CREATE_IF_NOT_EXISTS
      description: Create UK factory location. 
    selector:
      - display_name

    You may add a display_name and description to identify your location.

    {
   "display_name": "UK Factory",
   "description": "Industrial Warehouse in Bristol Harbor"
}

  3. Enter the required location name and address, or in the case of YAML and JSON, coordinates

    Adding the Location Details

    Use latitude and longitude to describe the physical location

    ---
steps:
  - step:
      action: LOCATIONS_CREATE_IF_NOT_EXISTS
      description: Create UK factory location. 
    selector:
      - display_name
    display_name: UK Factory
    description: Industrial Warehouse in Bristol Harbor
    latitude: 51.4477
    longitude: -2.5980

    Use latitude and longitude to describe the physical location

    {
   "display_name": "UK Factory",
   "description": "Industrial Warehouse in Bristol Harbor",
   "latitude": 51.4477,
   "longitude": -2.5980
}

  4. There is an option to add extended attributes to a location. This is useful to add metadata to a location, i.e. a site contact’s number and email address

    Use the Extended Attributes tab.

    Adding Extended Attributes to a Location

    Like Assets and Events, locations may also have extended attributes added as key-value pairs

    ---
steps:
  - step:
      action: LOCATIONS_CREATE_IF_NOT_EXISTS
      description: Create UK factory location. 
    selector:
      - display_name
    display_name: UK Factory
    description: Factory in Bristol Harbor
    latitude: 51.4477
    longitude: -2.5980
    attributes:
      address: Princes Wharf, Wapping Rd, Bristol BS1 4RN, UK
      Primary_Contact: Jill Tiller
      Primary_Mobile_Number: +447700900077

    Like Assets and Events, locations may also have extended attributes added as key-value pairs

    {
   "display_name": "UK Factory",
   "description": "Industrial Warehouse in Bristol Harbor",
   "latitude": 51.4477,
   "longitude": -2.5980,
   "attributes": {
     "address": "Princes Wharf, Wapping Rd, Bristol BS1 4RN, UK",
     "Primary_Contact": "Jill Tiller",
     "Primary_Mobile_Number": "+447700900077"
   }
}

  5. Complete your location

    Click Add Location.

    Submitting a Location

    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> \
      UK_factory_location.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/locations

  6. View your locations

    Navigate to Locations in the sidebar to see a list of existing locations.

    Managing a Location

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

    ---
steps:
  - step:
      action: LOCATIONS_LIST
      description: List all locations.
      print_response: true

    Use the Locations API to GET a list of existing locations.

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

  7. View details of the location you just created

    You can inspect details of a single location. Click the desired location row

    Viewing a Location

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

    ---
steps:
  - step:
      action: LOCATIONS_LIST
      description: Display Location named UK Factory. 
      print_response: true
    attrs: 
      arc_display_name: UK Factory

    Use the Locations API to GET the specific location by name.

    curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/v2/locations?display_name=UK%20Factory"

Assigning a Location to an Asset

Adding at Asset Creation

To assign a pre-existing location to an Asset during Asset creation, you need only select it

Choose the desired location from the Location drop-down.

Creating an Asset with an Existing Location

A pre-existing location can be added during Asset creation, using the Location ID as an identifier (e.g. locations/<location-id>).

---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset with pre-existing Location. 
      asset_label: My First Container 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    attributes: 
      arc_display_name: My First Container
      arc_display_type: Shipping Container
      arc_home_location_identity: <your-location-id>
    confirm: false

The YAML Runner also allows you to create new locations at Asset Creation.

---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset.
      asset_label: My First Container 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    attributes: 
      arc_display_name: My First Container
      arc_display_type: Shipping Container
    location: 
      selector: 
        - display_name
      display_name: UK Factory
      description: Container Origin
      latitude: 52.2025
      longitude: 0.1311
      attributes: 
        action: LOCATIONS_CREATE_IF_NOT_EXISTS
        location_label: UK Factory
    confirm: false

A pre-existing location can be added during Asset creation, using the Location ID as an identifier (e.g. locations/<location-id>).

{
    "behaviours": ["RecordEvidence"],
    "attributes": {
        "arc_display_name": "My First Container",
        "arc_display_type": "Traffic light with violation camera",
        "arc_home_location_identity": "locations/<location-id>"
    }
}

Adding to a pre-existing Asset

  1. To assign a pre-existing Asset with a new location, you need to identify the Location ID. To do this, view the location details by clicking the location row.

    Location Identity

  2. Then create an Event for the Asset and specify the identity of the new location as noted in step 1, against the arc_home_location_identity key
    For more information on creating Events, please visit Creating an Event Against an Asset.

    Updating an Existing Asset with a new Location

    The EVENTS_CREATE action must contain at least one key-value pair for event_attributes.

    ---
steps:
  - step:
      action: EVENTS_CREATE
      description: Add Location to existing Asset.
      asset_label: assets/<asset-id> 
    operation: Record
    behaviour: RecordEvidence
    event_attributes: 
      new_event: Record Asset Location
    asset_attributes:
      arc_home_location_identity: locations/<location-id>
    confirm: false

    {
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "asset_attributes": {
    "arc_home_location_identity": "locations/<location-id>"
  }
}
    Note - The Event must be recorded against the appropriate assets/<asset-id> when the curl command is executed. See Step 4 here for more details.
    Note - You need to include the full locations/<location-id> reference as using only the UUID will not be recognized.

  3. In the following screenshot, note the location of our Asset has been updated

    Completed update of Asset Location

← Compliance Policies