External Data Sources

Difficulty: expert

Suppose there are already sensors collecting data in the building and you want to include its data into the Workplace IOT platform. Spacewell provides a generic endpoint (using webhooks) for most of its sensor data types, to integrate, process and store sensor data from 3rd party platforms.

External Data Sources for beginners - an analogy

Since you’re on this page: looks like the sensors, that are in scope of sending data to the Workplace platform, are sending data to a platform or database that is not connected to Workplace. Working your way down this page, we’ll make sure that there is a connection set up between the platforms, that the data is send is a format that Workplace can work with and knows how to identify.

Setting up External Data Sources and sending data from an external database to the Workplace platform can be compared to “A car arrives at a gate. The car is known to the gate keeper, and the person in the car has a badge, because he told his contact person up front that he was coming.”

1. We want the external platform to send data to Workplace, which is why we use webhook with HTTP method “post”. This means the data gets pushed by the other system, and Workplace will not have to pull it from somewhere.
2. By creating an External Data Source in the tenant, you create a door or gate towards the Workplace platform: the Webhook URL. You’ll also receive the code to open the gate: the Authorization Token. Providing this information to the owners of the database, they are now able to reach the door.
3. But they need to present us the data in a way that we can consume! So they need to adhere to some rules:

   1. the data they send us must be meaningful: Workplace needs to be able to do something with that data (for example present them on a live floor plan or in a dashboard). So the External Data Source needs to provide the data in any of the 10+ supported data types.

   2. it’s not enough that they would just throw some data at us. In order to correctly interpret that data, it needs to adhere to a specific (payload) format. In this way, we know which part of the information to interpret as the device ID, which part as the value we need to store in the Workplace database etc.
4. For Spacewell to know where we need to store the data in our database, the sensor needs to be known on our end, and linked to a location. This is why the device needs to be registered in Studio. To register the device in Workplace Platform, you need:

   1. Device Type, which actually contains a preset of data types (per chosen DeviceType, a default set of channels is enabled).

   2. Device ID, which needs to be unique.

      1. In order to make this ID unique across all tenants, the device ID format includes the tenant ID

      2. In order to make this ID unique within the tenant, the device ID format includes the External Data Source ID
   3. Location information. If a sensor is not linked to a location, data is not stored in the Spacewell database.

the fact that the car is arriving at the gate without Spacewell needing to do anything is the webhook the supported data type was the instruction to present at a specific gate the brand and model of the car is the payload, the vehicle that is used to present the data the data is in the trunk of the car the sensor ID is the badge used for identification the device type is the gate number the gate is open thanks to the authorization token

Spacewell consultants that want to learn more about how Spacewell treats data that comes in, can check out Sensor raw data translated into timeslot data

The sensor vendor needs to comply with the Spacewell webhook, supported data types & payload.

How to set up this connection?

Steps described on this page:

1. In the external (customer or 3rd party) database: Configure data payload
2. Configure the connection between External Data Source and Workplace
3. Go to database and fill in URL and token, make sure to test the connection
4. Configure devices on Workplace platform
5. Devices send data to Workplace platform

Configure Data Payload

Webhooks

Webhooks provide a fast and secure way to reliably stream sensor data through from other systems.
The sensor provider is expected to post updates to the Spacewell endpoint.
The webhook endpoint expects a single HTTP request which represent a distinct message from the sensor.

• The webhook URL:

  • EU: <https://bohemian.eu1.cloud.cobundu.com/generic/<sensor_vendor>/data>

  • US: <https://bohemian.us1.cloud.cobundu.com/generic/<sensor_vendor>/data>
• HTTP method used: POST
• HTTP headers:

  • Authorization: Bearer <token>

  • Content-Type: application/json

Supported data types & payload

For all data types, it makes sense to verify if data will be send regularly or not; see https://onespacewell.atlassian.net/wiki/spaces/KB/pages/4357488644/External+Data+Sources#FAQ

Space occupancy related data types:

If your headcount device is able to track multiple count areas, you can send us the data of the individual count areas by replacing "<unique_device_id>" through "<unique_area_id>".

* The smallest time unit accepted by Workplace platform are seconds. Payload messages should not contain any milliseconds data

** Depending on the reliability of the sensor, space occupancy data may only contain data confirming “movement” (presence, headcount, footfall in one or the other direction etc), not the absence of movement… To tackle this in the Workplace platform, a decay feature has been introduced, which allows to visualize occupancy/headcount on the live (end user facing) floor plans for longer than what the data really tells us.

For an example on how Decay works, see Motion sensor

For a potential solution for data gaps in the dashboards (copy data in time slots), see https://onespacewell.atlassian.net/wiki/spaces/KB/pages/4357488644/External+Data+Sources#FAQ

Comfort related data types:

* The smallest time unit accepted by Workplace platform are seconds. Payload messages should not contain any milliseconds data

Indoor Air Quality related data types:

* The smallest time unit accepted by Workplace platform are seconds. Payload messages should not contain any milliseconds data

Battery related data types:

* The smallest time unit accepted by Workplace platform are seconds. Payload messages should not contain any milliseconds data

Configure the connection between External Data Source and Workplace

How to access

• Go to https://studio.cobundu.com/
• Login with your credentials
• Select Integrations > External Data Sources

1. Select “Add New”
2. Tenant ID will be filled in based on the environment that you logged in to
3. Fill in Source ID with a unique name, referring to your external data source

4. (Optional) Fill in a description, detailing what kind of data will come through the external data source
5. Copy the provided webhook URL + Authorization token to create the webhook in the external data source towards Spacewell Workplace
6. Make sure to enable your setup in Workplace

Test your setup

Once the webhook is created in the 3rd party database with above provided URL and token, make sure to test the connection.

This step is to be performed by the party that wants to send data to Spacewell Workplace.

Verify in a tool like Postman if your setup works:

• In case request is not successful, the endpoint returns 4xx-5xx status codes depending on the occurred issue.
• In case of successful request, the endpoint returns 200 status code with an empty body.

  • 200 code confirms that Workplace is receiving a message in JSON format, but does not validate that we can read/unpack the message. Check below chapter “Troubleshooting” in case of doubts.

Next steps

To create custom Device Types and configure your third party sensors in Workplace, see Custom Device Types

FAQ

Reach out to your Account Manager to set this up.