The KIHO connection brings the location and accumulated running hours of linked vehicles and devices from KIHO to Spots in Spotilla. Configure the settings in the browser. You need administrator rights, the KIHO integration enabled for your organization, KIHO credentials and permission to edit the Spot you want to link.

The KIHO credentials must provide access to the correct vehicle's location and running hours. A KIHO entity linked as a device must also have a vehicle connection in KIHO: its location and hours are retrieved from the associated vehicle. A device appearing in the selection list alone does not guarantee that data transfer will succeed.

Save the credentials and test the connection

  1. Open Settings → Integrations → KIHO and its Authentication tab.
  2. Select the Environment and Authentication method: API key, Username and password, Person number and PIN code or Client ID and tag. The default selections are Production and API key.
  3. Enter the credentials for the selected method. Enter the Client tag paired with the client ID. If a separate address has been provided for the connection, enter it in Base URL; otherwise, the default address is used.
  4. Select Save and then Test Connection. The test uses the saved details.

Production and Sandbox use the same default address. Selecting Sandbox alone therefore does not separate the connection from production data. A separate base URL must be an HTTPS address on the kiho.fi domain or one of its subdomains.

After a successful test, you will see the time when the connection was verified. The test checks authentication and connectivity; transferring data to Spots also requires spot mappings and synchronization to be enabled.

Previously saved secret values appear masked. Saving an empty or masked credential field preserves its previous value. Use the separate clear button to remove credentials.

Link a KIHO entity to a Spot

Open the KIHO connection's Settings tab and the Telemetry Sync section. The interface refers to links between Spots and KIHO entities as spot mappings.

  1. Select Link spot.
  2. Select the Spot in Spotilla.
  3. Search for and select the corresponding KIHO entity, for example by name or identifier. Entity type is filled in based on your selection.
  4. Check that you selected the correct device or vehicle, then select Link spot in the form.

You can see the current links using the Manage spot mappings button in the same section. The list shows the Spot, KIHO entity, External ID, entity type and Running hours. The running hours in the list are the previous reference reading saved in the mapping, rather than a new reading retrieved from KIHO in real time.

A Spot can have one KIHO mapping. Linking a new entity to an already linked Spot replaces its previous mapping. The same KIHO entity cannot be linked to multiple Spots, and entities that are already linked are excluded from search results. If you move an entity to another Spot, remove the old mapping first.

Preview and start the data transfer

  1. In the Telemetry Sync section, select Preview Spot Telemetry Sync. The preview does not change Spot data, mapping reference values or tag reads, and it does not trigger maintenance. It does not require In use to be selected.
  2. Wait for the preview to finish, then select the View Results button that appears alongside it.
  3. Check Action, Old location, New location, Old hours, New hours, Tag read and Reason on each row. Resolve any errors before enabling synchronization.
  4. Select In use in the Telemetry Sync section and save the settings.
  5. If you want to start the transfer immediately, select Run Spot Telemetry Sync. A notification that the job has been queued means it will run in the background.

Would update means that the location or running hours would change. No changes means that the update condition is not met. Missing spot, Invalid telemetry and Error require you to check the reason. A completed preview alone does not mean that every entity can be updated.

Old hours shows the higher of the Spot's reading and the mapping's reference reading. New hours shows the reading received from KIHO; a lower value may appear in this column even if it would not be saved. Tag read indicates whether the transfer would create an automatic tag read.

When synchronization is enabled, data is retrieved automatically approximately every ten minutes. The transfer direction is from KIHO to Spotilla. A manually started transfer also requires the In use selection to be saved. If a job is already queued or running, wait for it to finish.

How are location and running hours updated?

Location

The location query examines data from the last 15 minutes and selects the location with the latest timestamp. A valid location is saved to the Spot when it differs from the location previously saved in the mapping. Coordinates must be within valid geographic ranges; a coordinate pair consisting of two zeros is not accepted.

The update uses the same Spot coordinates as a manually set fixed location. A KIHO update can therefore overwrite a manually set location. Changes are compared against the mapping's previous location: a manually changed Spot location is not restored to the KIHO value if the KIHO location has not changed from the mapping's reference value.

Running hours

Running hours are the device's cumulative meter reading, rather than the hours accumulated since the previous transfer or an employee's working time. The KIHO reading replaces the Spot's reading only when it is greater than both the Spot's current reading and the previous reading saved in the mapping. An equal or lower value does not change the Spot's hours.

For example, if the Spot's reading has been corrected from 1,500 hours to 1,200 hours but the mapping has a saved reading of 1,500, a KIHO reading of 1,300 will not be applied to the Spot. A reading of 1,510 updates the Spot's value to 1,510. Correcting the Spot's reading downwards alone does not reset the KIHO mapping's reference reading.

Hours can be updated even if a successful location query returns an empty result or invalid coordinates. If the location request itself fails, the running hours for that entity are not retrieved. If retrieving the hours fails but the location is valid and has changed, the location can still be updated.

The reading can be updated even if the Spot's hourly maintenance feature is not enabled. When the feature is enabled, a changed reading is saved in the hour history unless the latest history row already contains the same value. Hourly maintenance templates linked to the Spot are also checked. Reaching a maintenance threshold can create a task and send a notification according to the template's settings. The advance setting, the reading at the previous maintenance and open maintenance tasks affect this. Check the templates before enabling automatic transfer; see configuring an hourly maintenance template.

Automatic tag read

When the location of an entity being updated has moved more than 50 metres from the location saved in the mapping during the previous update, the transfer creates a tag read. The first location alone does not create an event. The threshold applies to the distance between two locations, rather than the accumulated distance travelled.

The event is created automatically based on KIHO data. It does not mean that someone has read a physical NFC or QR tag. The event is assigned to the user of the Spot's most recent tag read that has a user, or, if there is no such event, to the first active mobile user. This assignment does not indicate that the person was near the device. If no user can be found for the assignment, that update fails.

Check the transfer results and investigate issues

Open the KIHO connection's Integration Logs tab. Filter the rows using the Time column and check Status and Message. Check both the overall transfer summary and errors for individual entities. The summary message includes the entities retrieved and updated, errors, any reason for stopping and the number of mappings left unprocessed.

A transfer may succeed only partially. An authentication error, exceeding the KIHO service's request limit or three consecutive temporary errors in the same type of query stops processing of the remaining mappings. Updates that have already succeeded are preserved. An error in the summary therefore does not mean that nothing was saved.

Also verify the result on the Spot itself. In the browser, open Assets, devices, tools → Default table, search for the Spot and open its details. Check Running machine hours and, if needed, the saved reading using the history icon next to the heading. For further instructions, see checking the running machine hours reading. Also check any tasks that the maintenance templates may have created.

In the Android and iOS apps, the same reading appears under Machine Hours in the Spot's details when the Spot's hourly maintenance feature is enabled. Reopen the Spot's details to check the current value. If needed, see opening a Spot in the mobile app.

If no entities are found, check that the KIHO credentials provide access to the correct vehicles or devices, and check for any existing mapping. Search results are limited to 200, so refine your search. If the transfer does not update the data, use the preview to check the vehicle connection, whether the location query succeeded and the reference values for hours. If authentication is blocked, correct and save the credentials again, then test the connection.

Remove a mapping or stop synchronization

To remove an individual link, open Telemetry Sync → Manage spot mappings, click the trash icon on the row and confirm removal. The Spot will then stop receiving data from that KIHO entity. Removal deletes the mapping and its reference values, but preserves the Spot, the location and hour data already saved to it, and its history.

Deleting a Spot also removes its KIHO mapping. Simply changing a Spot to any status other than deleted does not stop KIHO transfers. Remove the mapping or use the synchronization setting when you want to stop importing data.

To stop all KIHO telemetry synchronization, clear the In use selection and save the settings. This preserves the spot mappings, their reference values, connection credentials and previously saved data. Stopping synchronization does not remove maintenance tasks that have already been created.

If needed, remove the saved credentials using the Clear saved credentials button on the Authentication tab and confirm clearing. This also removes the connection's access token and verification time, but preserves the spot mappings and synchronization settings. Data transfer will then require new, working credentials.