Linking Workstations

Every physical workstation that a Shigoto Sensor is supposed to recognize and report must be linked once to the corresponding digital workstation in the partner system (pairing). This is done by an administrator of the customer using their own Shigoto Sensor.

The flow is similar to the activation flow of the Shigoto Sensor:

A user of the customer who was flagged as an administrator by the partner system during the activation of their Shigoto Sensor sees the administration area at the bottom of their Shigoto Sensor window, including the Link workstation button.
Link workstation shows a list of all devices the Shigoto Sensor currently detects and can use to identify a workstation. The administrator should open this list once before connecting to a physical workstation. This allows them to identify the devices that belong to their notebook rather than to a workstation, and to disable those.
When the administrator then connects their notebook to the physical workstation, the workstation's devices appear in the list. Based on these devices, they can start linking the physical workstation to the digital workstation in the partner system by clicking the Pair x device(s) button.
When the administrator clicks this button, the Shigoto Sensor opens a partner website agreed upon with the partner and passes it the sensor id and the URL of the Shigoto Hub for the linking:
```
https://<PartnerUrl>/sensor/Link.html
    ?sensorId=<sensorId>
    &validTill=2026-06-09T21:59:59.000Z
    &target=<shigoto-hub-url>
```
validTill is a timestamp that tells the called page how long the supplied sensorId remains valid.
Link.html should now give the administrator the possibility to select the digital workstation, for example based on building plans. On this digital workstation, the administrator should be able to invoke a command such as Link workstation.
When Link workstation is clicked, Link.html calls a REST API on the partner system and passes it the id of the workstation to be linked (e.g. https://<PartnerUrl>/sensor/link?sensorId=<sensorId>&hub=<shigoto-hub-url>&locationId=<locationId>). This link REST API then calls the linking on the Shigoto Hub via REST API and API key, where only the sensor id (also called client id) and the id of the digital workstation matter (see admin/pair). The devices to be linked are already known to the Shigoto Hub through its connection to the Shigoto Sensor.
Linking deliberately does not produce a booking: the administrator is configuring the workstation, not using it. For two minutes after the link, the first status report for the newly linked workstation is therefore held back; the regular report is only sent with the next change the sensor reports after that period. Partners that support the book parameter receive the report immediately instead, carrying book=false — see Reporting Sensor Status.

note

pair does not accept just a single workstation but a list, which is usually the hierarchical path to the actual workstation. Together with the locationName, Shigoto can use this to produce a more qualified output of the detected workstation.

For this use case, only passing the sensorId (as clientId) is meaningful — do not pass deviceSerialIDs or userName.