Reporting Sensor Status

Whenever the occupancy of a workstation changes, the Shigoto Hub reports this change to the partner with an API call.

For this purpose, the partner provides a REST API (e.g. https://<PartnerUrl>/sensor/report) and an API key.

Request

The API call (GET) receives the following parameters:

Parameter	Description
customerId	Id of the partner's customer.
userId	Id of the partner's user (only included if the user has not chosen to be anonymous).
locationId	Id of the partner's digital workstation.
state	Occupancy state of the workstation — see below.
anonymous	true if the user wants to work anonymously, otherwise false.
count	Number of users at this workstation as counted by Shigoto.
book	Whether the partner system should create a booking — see below. Only sent to partners for whom the parameter has been enabled.

The state parameter has one of the following values:

• occupied — the user has checked in at the workstation.
• locked — the user is checked in, but the screen is locked (AFK).
• leave — the user has left the workstation.

The book parameter has one of the following values:

• auto — the default. The partner system decides on its own whether a booking is created, exactly as it did before this parameter existed.
• true — create a booking in any case, and end an existing one if necessary.
• false — do not create a new booking, and leave an existing one alone.

book is switched off by default and is only sent once it has been agreed with the partner. Until then, the API call looks exactly as it did before.

Linking a workstation

While an administrator is linking a physical workstation to a digital one, no booking should be created — the workstation is being configured, not used. For the two minutes following a link, the Shigoto Hub therefore reports book=false. Partners for whom book is not enabled receive no status report at all during this period. Their regular report is only sent with the next change the sensor reports after these two minutes, which can take a while on a workstation that stays occupied. Partners who need the report right away should have book enabled.

Response

The API call should return the following answer to the Shigoto Hub as a JSON object:

• customer:
  • invalid or false: the partner's customer is no longer entitled to use SHIGOTO with the partner (no license or similar).
  • <display name>: the customer has been renamed. The Shigoto Hub stores the new name.
• user:
  • invalid or false: the partner's user is no longer entitled to use SHIGOTO. Their Shigoto Sensor is reset and their user account is deleted from the Shigoto Hub.
  • <display name>: the user has been renamed. The Shigoto Hub stores the new name.
• location:
  • invalid or false: the partner's workstation no longer exists. It is deleted from the Shigoto Hub, and a linked physical workstation must be paired again.
  • <workstation name>: the workstation has been renamed. The Shigoto Hub stores the new name.
• bookings: list of reservations for the reported workstation on the current day. The Shigoto Hub sends this information to the Shigoto Sensor, which can then decide — even in the anonymous case — whether the user has a valid reservation, and will notify the user if the workstation is reserved for someone else. The return value is a list of objects with the following fields:
  • from: start time, HH:mm in 24-hour format (e.g. 8:30)
  • to: end time, same format
  • userIds: list of user ids that have reserved this workstation. The older field userId with a single id is still accepted.
• capacity: number of people the workstation holds (optional, since version 2.3).
  • A positive number: that many people can use the workstation at the same time.
  • -1: unlimited — the workstation never counts as fully booked.
  • Missing or null: the Shigoto Hub keeps the capacity it already knows. Without any value, a capacity of 1 applies.

Example:

{
  "customer": "Example Ltd",
  "location": "Desk island 3",
  "capacity": 4,
  "bookings": [
    { "from": "8:00", "to": "12:30", "userIds": ["u-1001"] },
    { "from": "9:00", "to": "17:00", "userIds": ["u-1002"] }
  ]
}

Capacity and shared workstations

Bookings may be sent one by one, even if they overlap — for example one entry per person on a desk island. A single entry listing several people in userIds works as well. The Shigoto Sensor counts the distinct people booked at the same time and compares them with capacity:

• If the user has a booking of their own, the workstation counts as reserved for them, however many others are booked.
• Otherwise it only counts as reserved for someone else once the other people's bookings reach the capacity. Only then does the sensor warn the user.
• While seats are left, the sensor shows how many, e.g. "2 of 4 seats still available".

A capacity sent by the partner overwrites the value stored at the Shigoto Hub. For workstations whose partner sends no capacity, it can be set in the Shigoto portal instead.

Processing the status information

The partner system must decide on its own how to process the status information. In the simplest case, it creates a workstation reservation for the user (or an anonymous reservation) for the rest of the day, and completes the booking when the user leaves the workstation.