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.

Best Practices for UNITE API Usage:

All the unite customers are recommended to follow the below practices to ensure maximum performance of the APIs:

Adjust Polling Frequency: The system should schedule API calls only once or twice a day (if there’s no new data). Example: A customer, “ABC”, needs to get employee information and update their locations. So, they need to use two APIs:

1.           GET Employees API
   

2.           PUT Locations API
   

   Now, customer “ABC” should reduce how often they make these API calls. For example: The GET Employees API should be called once a day for each employee that needs to be updated. Similarly, the PUT Locations API should be called once a day for each location that needs updating.

Limit calls per second: We recommend a maximum of 2 calls per second

However, please note - If you have specific use cases and there is a need to have higher polling frequency than recommended, kindly reach out to our technical support team.

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:

Workers in the testing account The application access to workers can be given only from a productive account. This operation is not allowed from a testing account.

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.

User Activation API (Converting Worker to User)

Introduction: This API provides the capability to enable/activate a user(convert a worker to a user) via unite API.

API Specification: The existing PUT API for Employees(/workers/{{workerId}}) is modified to accommodate this functionality.

What has changed: In addition to the existing request body, three new attributes (isUser, roleId, email) are introduced to this API which should be specified in the request body in case of following scenarios:

• When enabling/activating a user, (converting worker to user)

  • "isUser": true, # mandatory field
  • "roleId": {integer value}, # mandatory field
  • "email": "user@unite.com" # mandatory field with valid email address

• When updating a user,(irrespective of user role) – updating any other user details except user role and email,

  • "isUser": true, # optional field, by default true if not specified
  • "roleId": {integer value}, # optional field
  • "email": "user@unite.com" # optional field

• When updating role of user

  • "isUser": true, # mandatory field
  • "roleId": {integer value}, # mandatory field
  • "email": "user@unite.com" # optional field

• When updating a worker,(who is not a user)

  • "isUser": false, # optional field, by default false
  • "roleId": {integer value}, # not required
  • "email": "user@unite.com" # not required

Limitations:

• Admin role cannot be enabled via this API. To enable admin role for a user please visit OnTrack UI.

• This API does not support domain users.

• Currently, we are supporting only “Everyone” and all custom roles.

• The Following roles are supported -

  • 1 (EVERYONE)
  • Custom Role (All Custom Roles are created for tenant)

• This API does not support creation of a new role.

• Currently, Unite APIs do not support creation of user, with this api modification we only convert a worker to a user.

User Deactivation API (Converting User to Worker)

Introduction: This API provides the capability to disable/de-activate a user via unite API.

API Specification: The existing PUT API for Employees(/workers/{{workerId}}) is modified to accommodate this functionality.

What has changed: In addition to the existing request body, three new attributes (isUser, roleId, email) are introduced to this API which should be specified in the request body in case of following scenarios:

• When disabling/de-activating a user
  • "isUser": false, # mandatory field
  • "roleId": {integer value}, # not required
  • "email": "user@unite.com" # not required

Limitations: Admin role cannot be disabled via this API. To disable admin role for a user please visit OnTrack UI.

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

Please refer to generic rules while using these apis

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, attachments, 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, attachments etc.)

Storage assets

Large assets that are used to store smaller assets within them (such as vans, containers) are referred as storage assets. ON!Track Unite API supports fetching, updating and transferring of assets to and from storage assets.

Here are few use cases concerning Storage Assets along with the steps to use the APIs:

Creating a VAN Storage Asset

• POST Asset (/assets) with "typeCode": "STORAGE": This will, by default, create a Storage Asset with subTypeCode as "CONTAINER"
• These fields are not applicable for POST Asset API : defaultParentOnTrackId, parentOnTrackId, defaultWorkerId
• PUT Asset (/assets) to change the subTypeCode as "VAN"

Updating Asset

• If an asset has a parentOnTrackId which is not NULL, then the PUT - /assets API request body for the same asset should contain only parentOnTrackId attribute and not currentLocationId attribute.
• If an asset has a defaultParentOnTrackId which is not NULL, then the PUT - /assets API request body for the same asset should contain defaultParentOnTrackId attribute and not defaultLocationId attribute.
• If an asset have parentOnTrackId and defaultParentOnTrackId and both are not NULL, then the PUT - /assets API request body for the same asset should contain both parentOnTrackId and defaultParentOnTrackId attributes and not currentLocationId and defaultLocationId attributes.

Fetching of Storage Asset details along with contained Assets and Quantity Item Allocations

• Get Asset by ID ( /assets/1667) - to fetch the details of the Storage Asset along with the count of contained Assets and Quantity Item Allocations
• Get List Assets (/assets?parentId=1667) - to fetch the list of contained Assets within the given storage asset
• Get List Allocations ( /quantity-item-allocations?parentAssetId=1667) - to fetch the list of contained Quantity Item Allocations within the given storage asset

Transferring a Normal Asset from and to a Storage Asset

• Create Transfer (/transfers) with fromStorageAssetId and toStorageAssetId set as identifiers of the source and destination Storage Assets

Fetching the Storage Asset Id for allocations of a given Quantity Item

• Get List Allocations ( /quantity-item-allocations?quantityItemIds=101) - to fetch the list of Quantity Item Allocations for the given Quantity Item. The response includes “allocationType” = “Storage Asset” “allocationTypeId” = “234” – This is the identifier of the parent Storage Asset for the Allocation

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

PUT and POST asset manufacturer It's important to notice that either the manufacturerId or the manufacturerName shall be written in POST and PUT calls, writing both data fields at the same time will result in an error.

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

Retrieving Manufacturers Data

GET API to retrieve all manufacturers - The GET List API provides easy access to comprehensive manufacturer data, streamlining your asset management process.

• API Endpoint : /manufacturers

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.

Completing an Open Asset Service

• POST API to Complete open service (/assets/{assetId}/open-services/{openServiceId}/complete) – to complete an open asset service with serviceAttachmentId as an identifier for document ID.

• serviceAttachmentId is same as ‘ontrackId’ parameter returned from the POST API (/documents).

Fetching Assets History Services

• GET API (/assets/{assetId}/history-services) - to fetch services history details with attachmentCount in the response.The "attachmentCount" attribute returns the total number of attachments which include both the ones uploaded by user during completing an open service and the ones which already exist in service template.

• GET API (/assets/{assetId}/history-services/{historyServiceId}) – to fetch services history details with attachments details for an asset.This API only returns the attachments uploaded by the user, and does not return the attachments from service template

• These attachments can then be downloaded by the GET API for retrieving attachments(/documents/{documentId}/pre-signed-url), where documentId is same as serviceAttachmentId.

Generic Usage Rules

• We don’t recommend copying the response of GET API and pasting it to the request body of PUT API directly because they might differ in few attributes.

• All APIs should be treated independently unless specifically stated in case of exceptional scenarios.

Document Support for Assets

We have started to introduce APIs to support attaching documents to entities Assets and Services. At the moment ON!Track Unite API supports creation of asset with attachment, creation & retrieval of attachments, completion of open asset service using attachments and fetching assets history services using attachments.

Here are the few use cases concerning asset attachments along with API endpoints:

Creating/Uploading a Document

• POST API to upload documents (/documents) with file & associatedEntity as identifiers for attachment and entity(‘AssetOpenService’, 'Asset') respectively.
• Existing POST / PUT API for creation and updating an asset with attaching document:
  • Only Single attachment per API call is allowed.
  • "displayName" attribute is optional.
  • "fileName" attribute is not required.
  • Supported attachment types are [.pdf, .docx, .rtf, .odt, .xlsx, .txt, .png, .jpg, .jpeg, .bmp]

Retrieving/Downloading a Document

• GET API to retrieve documents (/documents/{documentId}/pre-signed-url) – to fetch pre-signed url to download documents along with expiry time.

• GET API to retrieve asset images (/documents/{documentId}/pre-signed-url) – to fetch pre-signed url to download asset images along with expiry time.

  Note: here documentId is the assetImageId retrieved from the response of Assets GET API.

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.

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

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:

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

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

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

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

filter=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:

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

Rentals APIs

These APIs are only available for On!Track Pro customers who have purchased Runtime Tags (available to rental companies only).

These APIs are targeted for Rental customers to enable them to avail DDS using Runtime Tags.

APIs to fetch Runtime data for single & bulk assets:

• GET API (/runtimedata/{assetId}) to retrieve runtime data for single asset -accepts assetId as an attribute and returns the runtime data for that asset.
• GET API (/runtimedata) to retrieve runtime data for bulk assets :
  • If the optional parameter “afterDateTime” is specified, then the API returns the runtime data after that specified date.
  • If the optional parameter “afterDateTime” is not specified, then the API returns the runtime data for last 7 days.

APIs to fetch Usage history data for single & bulk assets:

It will return last 32 days data based on the last updated timestamp.

• GET API (/usage-history/{assetId}) to fetch usage history data for single asset - accepts assetId as an attribute and returns the usage history data for that asset.
  • If the optional parameter “afterDate” is specified, then the API returns the usage history data after that specified date.
  • If the optional parameter “afterDate” is not specified, then the API returns the usage history data for last 7 days.
• GET API (/usage-history) to fetch usage history data for bulk assets :
  • If the optional parameter “afterDate” is specified, then the API returns the usage history data after that specified date.
  • If the optional parameter “afterDate” is not specified, then the API returns the usage history data for last 7 days.

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"
],

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.

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.