ON!Track Unite tutorial

Working with ON!Track and its API

This section offers detailed instructions on how to best work with ON!Track and its available APIs, divided per item type (workers, locations and assets). In particular, it points out the business logics that have been implemented and shall be considered when building integrations with ON!Track.

Out of the many modules and functionalities that ON!Track offers, in this section we describe those having a direct impact on the integrations and API.

Workers

The very first item to be created in ON!Track are the workers, as they are needed to further create locations and then assets. The only mandatory information to create a worker via API is the first and last name but more details can be added such as designation, identification details, contact information and certificates. Not all available data fields in ON!Track are part of the worker API endpoint refer to the API documentation for the worker to have a detailed overview. No worker certificate or attachment can be added via API.

By default, all workers created via API will not be given ON!Track’s application access, that can be granted by editing the worker’s detail from ON!Track, as shown in the example below:

The current API endpoints allow to create workers from an external system, as well as editing the details of a worker previously created. The delete operations via API is not supported.

Locations

In ON!Track locations are categorized as either jobsites or warehouses. Larger equipment that is used to store assets within them (such as vans and containers) are referred to as storage assets and are not considered locations, they shall instead be created as assets.

The mandatory information to create a location via API are:

• Type: jobsite or warehouse
• Name: chosen name of the location
• Location State: Active, Inactive or Archived (for which only outgoing asset transfers are possible)
• Location Manager: the worker who is responsible for the location, to be selected among the workers previously created

The available API endpoints allow to add many optional details when creating or editing a location, such as additional identification details, cost center and address. Although ON!Track allows to create a location hierarchy, by default all locations created via API are added as parent. The locations hierarchy can be modified from the ON!Track application by editing the details of the locations previously created via API as shown in the example below:

The current API endpoints allow to create locations from an external system, as well as editing the details of a location previously created. The delete operations via API is not supported but it is possible to archive locations if no assets are assigned to them.

Assets

In ON!Track assets are all these items and equipment (from every manufacturer) that have a serial number, therefore it makes sense to manage as a unique item. On the contrary, consumables and commodities that typically do not have a serial number shall be managed as quantity items (the API endpoints for quantity items are not currently available).

The current API endpoints allow to create assets from an external system, as well as editing the details of an asset previously created and deleting the assets. It is also not possible to assign via API to an asset services, attachments and asset cost information.

Creating assets via API

Unique assets shall be tagged with smart tags or with a barcode to be correctly utilized with ON!Track. However, when creating new assets via API in ON!Track the scan code information might be missing in the external system. Therefore, there are two different scenarios and proposed processes to create assets in ON!Track, according to whether the asset scan code data is stored in the external system. In both cases, the assets shall always be created in a warehouse for the first time (i.e. set a warehouse as default location).

The scan code is missing in the external system

1. Leave empty both the Scan code type and Scan code data fields of the API
2. Add all the mandatory information to create an asset
   • Inventory number: identifier of the asset in the tool park (for assets created via API, this information can be added after the asset creation directly in the ON!Track app)
   • Default location: the main location for that asset, chosen from the list of locations previously created (always set a warehouse as default location)
   • Responsible worker: the worker who is currently responsible for the asset, to be selected among the workers previously created
   • Owner: the worker who is generally responsible for the asset (can be the same as the responsible worker), to be selected among the workers previously created
   • Ownership type: to be selected among owned, fleet, loaned, or rented
3. Open the ON!Track application, start the edit workflow for the assets just created, and select the Scan code type (Barcode or ON!Track smart tag) and the Scan code
4. Add additional optional information via API (such as manufacturer and model, name, status, cost details, etc.) if needed

The scan code is present in the external system

1. Add all the mandatory information in the API
   • Scan code type: either Barcode or ON!Track smart tag
   • Scan code: the unique code that can be found on the barcode label or the ON!Track smart tag (for assets created via API, this information can be added after the asset creation directly in the ON!Track app)
   • Inventory number: identifier of the asset in the tool park (for assets created via API, this information can be added after the asset creation directly in the ON!Track app)
   • Default location: the main location for that asset, chosen from the list of locations previously created (always set a warehouse as default location)
   • Responsible worker: the worker who is currently responsible for the asset, to be selected among the workers previously created
   • Owner: the worker who is generally responsible for the asset (can be the same as the responsible worker), to be selected among the workers previously created
   • Ownership type: to be selected among owned, fleet, loaned, or rented
2. Add additional optional information via API (such as manufacturer and model, name, status, cost details, etc.)

Storage assets

Large assets that are used to store smaller assets within them (such as vans and containers) are referred as storage assets. Only read operations are supported for the storage assets by the ON!Track Unite API.

Asset Usage Conditions

The Asset Usage Condition (AUC) is a parameter used to link the status of an asset to its billability. The AUC has these statuses:

• Active: Billable (when assets are transferred to a jobsite, are set to Active by default)
• Bad Weather Condition: Non-Billable
• Not Working: Non-Billable
• Passive: Non-Billable (when assets are transferred to a warehouse, are set to Passive by default)
• Paused: Non-Billable
• Ready to Pick: Non-Billable

The different AUC can be set in ON!Track by editing the relevant asset, and there is also the option to mark the date when the AUC change happened, as shown in the example below:

This information can be then be retrieved via API by the external system, typically an ERP, to trigger relevant accounting-related processes. It is not recommended to set or edit the AUC via API from an external system.

Asset templates

Asset templates allow to pre-define a set of common data to be assigned to all assets with the same manufacturer and model. Using templates eases the creation and editing process of the assets a template is assigned to, as the data entered in template are reflected across all assets that use that template.

When an asset is created or edited via API, it is assigned to a template only when both the Model and the Manufacturer are specified in the API call. If a template for that particular manufacturer and model is already existing in ON!Track, the template is assigned to an asset created via API. In case that the template for that model and manufacturer combination is not existing, the asset creation via API triggers the creation of an asset template.

Working with asset templates and API has the following limitations:

• No asset template data can be modified via API
• The asset data controlled by the template (for example description and group) cannot be modified via API for those assets that have a template assigned

Asset manufacturer

Two alternative data fields can be used to write the asset manufacturer in ON!Track:

• manufacturerId: a unique code assigned automatically by ON!Track to a specific manufacturer, in the POST and PUT calls this field can be used after having performed a GET call and read out from ON!Track the ID assigned to a given manufacturer
• manufacturerName: the actual name of the manufacturer, that can be written freely and new manufacturer will be given a new ID

Assets manufactured by Hilti

Certain data and information of assets manufactured by Hilti can be automatically be populated in ON!Track from the internal Hilti’s database, by using the asset template function. In this context, the linking of these assets with an external system via API needs to be carefully managed to avoid possible mismatches or duplication of assets. To do so, there are two alternatives:

ON!Track as master

1. Go to the ON!Track application and click on “Add” in the asset tab to create an asset manually into ON!Track
2. When selecting Hilti as manufacturer, a guided procedure is triggered and that leads to correctly linking the asset with the Hilti internal database
3. At this point relevant data are automatically populated from the Hilti database and you shall complete the asset creation process with the missing information and press complete when done
4. With a GET call, you can retrieve the Hilti asset data to be used in the external system

External system as master

1. Import the asset data into ON!Track from an external system via API as previously described, make sure to add the manufacturer information
2. In the ON!Track application, edit the details of the asset just created
3. When the manufacturer is set to “Hilti”, by clicking on the model field you are presented with the option to choose among Hilti provided templates as well as a list of unregistered Hilti assets that you can select (that represents all Hilti assets that your company owns, that were not previously registered in ON!Track)
4. At this point, the linking with the internal Hilti database is set and the additional data are automatically populated from it, these data can now be exported via API to the external system if needed

Current location

The current asset location can generally be read (“GET”) from ON!Track via API, be assigned to an asset while being created via API (“POST”) or edited (“PUT”) to any asset after it is created but before it is transferred the first time. It is not possible to edit via API the current location after that asset was transferred at least one time. In this case, to change the current location we recommend using the transfer functionality in the user interface (web or mobile).

Geolocation

Assets that use ON!Track BLE tags can be scanned either by the ON!Track bluetooth gateway or by mobile devices with the ON!Track app (with bluetooth functionality active). Information on asset location are then made accesible via the asset geolocation API that returns the coordinates of where your asset was last scanned at. Please note below a few watch-outs.

1. An asset can be scanned via multiple methods and many times over the day; the Geolocation API prioritizes the data to give you the most recent and accurate scan entry.
2. The Geolocation API should show you information on when and where the asset was last scanned, due to the dynamic nature of assets being used in the field, the more recent a scan the more accurate the information should be.
3. If an asset is scanned via bluetooth scanning, we are able to capture not only the Geo-coordinates, but also the altitude as well as the accuracy of the data, here active scanning will give you higher accuracy than background scanning.
4. If an asset is scanned at a gateway, the API will not only return the ID of the location the gateway is installed at but also the Geo-coordinates of the location, which is why for most accurate information, its recommended that a user fill in Longitude and Latitude of all gateway locations within the ON!Track application.

Asset Services and Maintenance dates

We have started to introduce APIs to manage asset services and maintenance dates. At the moment it is possible to get (i.e. read) the list of open services attached to a given asset. In the coming releases we will expand the service APIs with additional reading as well as writing functionalities

Quantity items

In ON!Track, quantity items are items or materials (from every manufacturer) that are available with multiple stock and a stock unit, like consumables and commodities that typically do not have a serial number. The current API endpoints allow to create quantity items from an external system, as well as editing the details of a quantity items and its allocation previously created.

Catalog items

With the create quantity items workflow, it is possible to reflect in ON!Track the catalog of quantity items present in the external system, or vice versa. In other words, the stock-keeping units can be synchronized between ON!Track and the external system via API. We support the whole CRUD operations for quantity items. Deleting quantity items is only allowed if no allocations are assigned to it.

Units

When creating a new quantity item, it is important to assign the right stock unit (or unit of measurement). While adding new quantity items a Unit ID can be selected from our predefined list of unit IDs presented below. In case you would like using custom units, please reach out to the ON!Track Unite support team.

Allocations

Allocations represent all the places where quantity items are stored, they can be locations, storage assets or employees. It is possible not only to perform the whole CRUD operations via API, but also to restock and overwrite stock (e.g. overwrite new stock after a performed inventory check) of a given quantity item’s allocation. Also changing the status within a quantity item allocation e.g. consumption is possible via API. Allocations also can be deleted if they are main allocations and have zero stock. Non-main allocations with zero stock are removed automatically from the system.

The quantity item allocation API will also return the current stock levels of the given quantity item in all the different allocations.

Asset and Quantity items transfers

Within the ON!Track web and mobile application, users can transfer assets and quantity items from one location to another. The transfer information (transfer ID, time stamps, transfer notes, task code, asset/quantity item ID, external ID, asset type, from/to location, from/to employee, stock quantity, stock status) can be retrieved via API and used, for example, to calculate the residence time of assets and quantity items in any given location as input for cost allocation or other processes and uses. To understand if a transfer involves quantity items or assets, please refer to the “AssetTransferType” data field.

Backdated transfers

When transfers are created with a day in the past, the time when the transfer was conducted in ON!Track is referred to as “submittedTimestamp” while the “transferTimestamp” represents the time when the transfer took place (potentially in the past). The GET transfer list is ordered by default with the “transferTimestamp” (more recent transfer first).

Confirm delivery

When the confirmed delivery functionality is activated for a transfer, the data of that transfer are exposed via API (in the GET transfer list) only when all assets have been confirmed or rejected by the transfer’s receiver. In other words, the transfer is not shown until there are still some assets in transit.

Quantity items transfers and consumptions

There are two ways of getting an overview of the quantity items utilization and thereby the possibility to bill:

• Transfers: Use the get transfer list API for getting information regarding quantity items movement from one location to another, this is particularly useful for commodities that are charged on a daily basis to jobsites
• Consumption per allocation: Get the quantity items per allocation to check what quantity items have been consumed on a given allocation and thereby charging the relative cost center in the ERP

Transfer filters

It is possible to filter the GET transfer list to obtain only a subset of transfers based on the submitted and transfered dates.

In particular, to get transfers after a given dates, the code to be used is:

For dates equal or greater than YYYY-MM-DD:

filters=transferDate%3Age%3DYYYY-MM-DD

For dates equal or lower than YYYY-MM-DD:

filters=transferDate%3Ale%3DYYYY-MM-DD

For an interval of dates between YYYY-MM-DD and yyyy-mm-dd

filters=transferDate%3Age%3DYYYY-MM-DD,transferDate%3Ale%3Dyyyy-mm-dd

For example, the code to get the transfer that took place in the previous month October 2021 the filter for the code is:

filters=transferDate%3Age=2021-10-01,transferDate%3Ale%3D2021-10-31

Labels

Labels are customizable attributes that can be added to workers, locations, assets, and quantity items. They can be used to create a customized grouping and to facilitate the searching process in ON!Track. Labels can be added both via API by creating entities and directly in the ON!Track application.

The correct syntax for adding or editing labels is:

"labels": [
"Label1",
"Label2"
],

External ID

The External ID represents the unique identification code of an item (workers, locations, assets, and quantity items) used in the external system. It is a field that will be shown in the ON!Track UI only to users that signed for the ON!Track Unite add-on.

For new items created in ON!Track from an external system, the External ID is written directly in ON!Track via API. For all these items that exist both in ON!Track and in the external system, it is recommended to write the same external ID in all items both in ON!Track and in the external system. By doing so, the same item can be correctly matched in the two systems and the creation of duplicates is avoided.

It is also possible for ON!Track customers to search for the External IDs of the external system in the ON!Track Web UI in order to identify an asset.

ON!Track ID

The ON!Track ID is the unique identifier that ON!Track automatically generates and assigns to all items (workers, locations, assets, and quantity items). Therefore, this data field shall be left blank in all POST calls, but it is used in the GET, PUT, and DELETE calls as the unique identifier for referencing a specific item.

Standard data fields

Certain data fields needed in the creation of workers, locations and employees rely on these standard values:

• Country codes
• State/region codes
• Language codes
• Currency codes

To successfully write items in ON!Track it is necessary to utilize the correct standard codes it is therefore needed to first perform the GET call to read these codes and utilize these in the POST and PUT calls.