RKVST

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.

Creating a Location

  1. Create your location.

In the dashboard, select Locations, then Add Location.

Adding a Location

The RKVST 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.

{

}
  1. 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"
}
  1. 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",
   "lattitude": 51.4477,
   "longitude": -2.5980
}
  1. 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",
   "lattitude": 51.4477,
   "longitude": -2.5980,
   "attributes": {
     "address": "Princes Wharf, Wapping Rd, Bristol BS1 4RN, UK",
     "Primary_Contact": "Jill Tiller",
     "Primary_Mobile_Number": "+447700900077"
   }
}
  1. Complete your location.

Click Add Location.

Submitting a Location

Use the archivist_runner to run your YAML file!

$ archivist_runner \
      -u https://app.rkvst.io \
      --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 "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v2/locations
  1. 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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v2/locations
  1. 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 "@$BEARER_TOKEN_FILE" \
     "https://app.rkvst.io/archivist/v2/locations?display_name=UK%20Factory"

Assigning a Location to an Asset

Adding at Asset Creation

  1. 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-exisiting 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: true

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: true

A pre-exisiting 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
  1. 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
Note - 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: true

{
  "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.
  1. In the following screenshot, note the location of our Asset has been updated.
Completed update of Asset Location

Edit this page on GitHub

← Compliance Policies
Dropbox Integration →