Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

Version 1 Next »

Difficulty: expert

Content

Learning Objectives

After reading this article, you’ll be able to:

  • understand what Workplace APIs can do

  • test Workplace APIs

API stands for Application Programming Interface and allows easy exchange of data and functionality. The Workplace API documentation (Swagger) is available in a separate tab in the GO menu.

How to access Workplace API

The option appears only for users who have a developer or admin role assigned to them. See Roles & Profiles for more information.

To use the APIs in your own projects (eg postman), you might be interested to use the swagger.json-link. As you can see in the screenshot, "latest" page opens per default, but this is of course subject to change.

Use numbered versions (eg https://go.cobundu.com/rest/v3/docs) to avoid conflicts.

Using a specific version has the advantage of being able to compare API versions in future.

Testing the API: examples

It's possible to try out/test the Workplace API. Depending on the request, you might need to fill in some information first.

Example 1. Get the list of sensor devices

  1. Select "Try it out",

  2. then "Execute",

  3. to get a list of all sensor devices currently linked to this tenant.

As you can see in the example, each sensor channel (eg humidity, temperature and CO2 in a comfort sensor) is delivered separately.

Example 2. Get the current sensor data for a location

  1. Select "Try it out",

  2. Add the mandatory location ID

  3. then "Execute",

  4. to get the current sensor data of all sensors that are linked to that location.

As you can see in the example, 1 comfort sensor is linked to the requested location. Therefore all channel values available for this sensor (temperature and humidity in this case) are delivered, as well as the timestamp for which these values were received.

Below examples mention “location ID”. Selecting a location on https://go.cobundu.com/ will show the Reference, e.g. "Meeting Room 1". But in the Workplace back-end, each location has a unique location ID.

Location ID is available in the Workplace back-end https://studio.cobundu.com URL for each selected location.

For example the Location ID for floor “2nd floor” in Spacewell Antwerp offices is “910000000004545”

Example 3. Reservations

To retrieve the reservations from your environment, you can use Reservations API > "get a list of bookings".
Modify dates in the search instruction and to get (filtered) reservations, each including the location ID, thus indicating which location was booked.
Enter location IDs in the search filter to get filtered data.

Example 4. Get location information

Selecting a location on https://go.cobundu.com/ will show the Reference, e.g. "Meeting Room 1". But in the Workplace back-end, each location has a unique location ID.


Locations API can help you get that information.
Depending on what is needed:

  • get a list of locations for this client

  • request specific location information (for example information on a set of workplaces): "get location tree" (filter top-level results = workplace)

Example 5. Floor plan

To get a Workplace floor plan, select API Locations > "get a location's drawing as SVG"
The requested location ID in this case is the floor ID.
"Testing" in swagger will provide a response, but it cannot show the SVG.

Enter the floor location ID in following URL to see the SVG: https://go.eu1.cloud.cobundu.com/rest/latest/locations/floor location ID/drawing/svg

Concrete use case: URL to show live floorplan

Imagine you want to push a URL to your kiosk screens to visualize Workplace live floorplan data.

Here, we suggest to provide an acces token with a URL, so that anyone with the link can see the live floorplan.

Alternative methods and Frequently Asked Questions about this can be found here: Workplace live floorplan data visualization

The below suggested dedicated method includes web authentication via Rest API. This means a Workplace login + password are needed, and the API will return a JWT token which can be used to access all other API calls.

Prerequisites

  • Web kiosk needs to be configured in Studio

  • Per floor for which you want to set up visualization, a Workplace user is needed:

    • Workplace minimum rights/no specific role needed

    • taking into account reservation features set up for this environment

    • User name + password

  • To access API: Workplace user with either Admin or Developer role

Solution

  1. Using API to get session token

    1. Go to http://go.cobundu.com (user needs either Admin or Developer role) >  API

      1. Select "auth" > /rest/latest/auth/ssosettings/{loginId} (return sso settings for the user)

      2. Provide user name

      3.  Response body will provide the host name of cobundu SSO instance that needs to be used (Workplace IoT Platform is available for EU and US) (could be eg  "apiUrl": https://go.eu1.cloud.cobundu.com )

    2. Still on http://go.cobundu.com (user needs either Admin or Developer role) >  API

      1. Select "auth" >  /rest/latest/login (authenticate user)

      2. Specify username + password that will be used to access live data

      3. Change the login parameters "rememberme": true, "setCookie": true

      4.  Response body will provide accessToken

      6. Access token is ready to be used

  2. Prepare Web kiosk URL

    1. Go to http://go.cobundu.com (user needs either Admin or Developer role) > Kiosk Mode

    2. Select the relevant floor > open web kiosk

    3. Web Kiosk URL will have format https://go.cobundu.com/kiosk/MEETING%7C1d18e8b0-48a7-464c-8813-66608b474d6d

    4. Replace root domain of the URL to indicate to the correct cloud end-point (EU or US), you'll obtain eg https://go.eu1.cloud.cobundu.com/kiosk/MEETING| ...

    5. Add suffix "?jwt=" and copy/paste accessToken at the end of the URL

  3. Access this URL (for example in incognito mode), and the web kiosk will open on the chosen floor without asking for identification. A session refresh will run inside the application every 10 minutes.

    1. After the token is obtained, there are 10 minutes to pass it in the URL to open the floor plan.

    2. After the floor plan is loaded, further token renewal will run automatically without session loss or any manual intervention.

Limitations

  • Web kiosk shows Reservation view (= combined Occupancy and Reservations data (if available))

  • If browser crashes/computer is unplugged: restart the process to get a new access token

Search

  • No labels