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.
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.
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:
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.
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.
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
The scan code is present in the external system
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.
The Asset Usage Condition (AUC) is a parameter used to link the status of an asset to its billability. The AUC has these statuses:
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 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:
Two alternative data fields can be used to write the asset manufacturer in ON!Track:
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
External system as master
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).
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.
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
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.
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.
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.
ID | Unit | Description |
---|---|---|
1 | box | Box |
2 | can | Can |
3 | pc | Piece |
4 | ft | Feet |
5 | kg | Kilogram |
6 | lb | Pound |
7 | m | Meter |
8 | sheet | Sheet |
9 | ton | Ton |
10 | yd | Yard |
11 | liter | Liter |
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.
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.
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).
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.
There are two ways of getting an overview of the quantity items utilization and thereby the possibility to bill:
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 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"
],
Labels for imported items
We highly recommend creating via API a label for all assets, quantity items, locations, and workers imported into ON!Track from an external system. The text of the label shall be "Imported from external system XYZ", where XYZ is the name of the software source of the item's data.
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.
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.
Certain data fields needed in the creation of workers, locations and employees rely on these standard values:
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.