Introduction

It's very common to find occupancy schedules that define for a floor, a space or an equipment when systems should be in a standby mode or at optimum work and when it should be simply off.

From a supervisory head-end, it usually look like this with some Regular events (a start hour and an end hour is defined for every day of every week)


 And you can create special events such as Monday 15th of August 2022 from 09am to 12p or more advanced ones (every first Monday of the month...)


Well both these events are available through the API.

Discover schedules

Let's assume you want to discover all available schedules of a particular floor.

First let's discover all the floors of the site with /v1/explore/hierarchies using the StructureAssets hierarchy. (See Linksper assets hierarchies)

GET {{base-api-url}}/v1/explore/hierarchies/StructureAssets?depth=3


We use VayanData office in the above example. A level 3 depth is enough to get the definition of every floor. We can spot the Level 2


Let's copy its unique id:  2MhuM4MG90Vw6o5JdtYxTm

Let's now use another endpoint to get all schedules relative to an asset, the Level 2 in our case.

GET {{base-api-url}}/v1/explore/assets/2MhuM4MG90Vw6o5JdtYxTm/schedules


We can see there is one schedule associated with the floor:

Few things to notice here:

  • We can get the current value with the field "dataValue", it's currently set as Unoccupied.
  • Next change is the next day at 7am (UTC) for the "Occupied" value
  • We can see with the range field all the possible values we can find on this particular Schedule.
  • And finally we can retrieve its unique id: T0T4oTdQB1DqLpMkYjpfz



Create a new recurring event


Great now, let use the /v1/operate/schedules/id to create a recurring event: every Saturday morning from 09am to 11am for the cleaning team.

POST {{base-api-url}}/v1/operate/schedules/T0T4oTdQB1DqLpMkYjpfz/recurringEvents

According to the documentation, we will inject in the body

{
  "day": "saturday",
  "startTime": "09:00:00.000Z",
  "endTime": "11:00:00.000Z",
  "value": "Occupied"
}

This is the answer we get:

And if we check the BOS UI;

You can then update a recurring events, delete etc.