Difficulty: expert

Content

Table of Contents

minLevel	1
maxLevel	1

Learning Objectives

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

Identify which data types are supported by Spacewell Workplace
Configure webhook & authorization token to connect your external data sources to Workplace

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.

Expand

title	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.”

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.
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.
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.
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 /wiki/spaces/WM/pages/492237

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

Info
Within 1 vendor ID, sensor IDs need to be unique and prepended with the vendor ID. Combining device IDs from multiple third parties in 1 External Data Source, raises the potential risk of conflicts.

How to set up this connection?

Steps described on this page:

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://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

Space occupancy related data types:

Expand

title	PIR*: space occupancy

Code Block

language	json

{
"device": "<unique_device_id>", // string: unique id of the device
"type": "pir", // string: pir for occupancy
"timestamp": "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
"value": "1" // string: 0 or 1, 0 = not occupied, 1 = occupied
}

Expand

title	Headcount*: for measuring number of people

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device or count area
“type”: "headcount", // string: headcount for measuring number of people
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "10" // string: value is unsigned integer
}

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>".

Expand

title	Pulse: for door counters sending pulse values

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "pulse", // string: pulse for door counters sending pulse values
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1" // string: count of pulses expressed as unsigned integer
}

Expand

title	Counter: for door counters sending accumulated values

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "counter", // string: count for door counters sending accumulated values 
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "10" // string: value is unsigned integer
}

Expand

title	Footfall-in pulse*

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "footfall-in-pulse", // string: footfall in pulse sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "5" // string: count of in pulses expressed as unsigned integer
}

Expand

title	Footfall-out pulse*

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "footfall-out-pulse", // string: footfall out pulse sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "3" // string: count of out pulses expressed as unsigned integer
}

Expand

title	Parking*

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "pir", // string: pir for occupancy
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1" // string: 0 or 1, 0 = not occupied, 1 = occupied
}

* 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 https://spacewell.atlassian.net/wiki/spaces/KB/pages/491737/Motion+sensor#How-is-Motion-sensor-data-reflected-in-Workplace-Live-Views%3F

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

Comfort related data types:

Expand

title	Temperature

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "temperature", // string: temperature sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "25.5" // string: value in Celsius expressed as double with dot as decimal separator
}

Expand

title	Humidity

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "humidity", // string: humidity sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "75.5" // string: value in percentage 0-100
                     // expressed as double with dot as decimal separator
}

Indoor Air Quality related data types:

Expand

title	CO2

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "co2", // string: co2 for carbon dioxide sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "555.5" // string: measured value of CO2 in the air (parts per million)
                       // expressed as double with dot as decimal separator
}

Expand

title	TVOC (Total volatile organic compounds)

Code Block

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "voc", // string: voc for volatile organic compounds
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "1.0" // string: measured value of VOC in the air (parts per billion)
                   // expressed as double with dot as decimal separator
}

Expand

title	Radon

Code Block

language	json

{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "radon", // string: radon sensor
“timestamp”: "2020-09-22T14:27:36Z", // string: ISO 8601 date and time
“value”: "19.0" // string: radon level measured is Becquerels per cubic meter, Bq/m3
                     // expressed as double with dot as decimal separator

}

Info
Best practice is to test this in a sandbox environment locally first

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 in the Studio 2.0 interface

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

Note
In Source ID field, only use alphanumeric values. The Source ID will later be used as a component of the device IDs.

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

Info
It’s possible to refresh the Authorization Token in Studio. Remember that this new token now also needs to be updated in the 3rd party platform.

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.

Check below chapter “Troubleshooting” in case of doubts.

Next steps

To create custom Device Types and configure your third party sensors in Workplace, see https://spacewell.atlassian.net/wiki/pages/resumedraft.action?draftId=579142021&draftShareId=e6b92d46-f85a-4de1-a6d5-7cf4b9036b75

FAQ

Expand

title	What if the sensor does not regularly send data? Is it possible to copy data in timeslots?

Depending on the kind of sensor, they might not send heartbeats or data regularly. If they send data and then only send a message upon value change, you might find yourself with bits and pieces of data (eg 1 time slot of 15 minutes with data about temperature, and nothing the rest of the day), which would cause confusion when you try to read the dashboards.

To work around this, you can opt to have Spacewell copy the data, per generic endpoint / device type level for any desired amount of time.

For example for the sensor type "Generic PIR" we could set a "copy in further time slots" and this value would be valid for all Generic PIR sensor values, which come to us for your tenant. Of course, the data is only copied until new data comes in again. So if a value comes in on Monday at 9am, and the configuration says "copy for 7 days", and on Wednesday at 8am a new value comes in, then from Wednesday at 8am the new value is taken for 7 days, or until a new value comes in.

Info
Consequently, Workplace will only visualize or report if a sensor is NOT transmitting data after the configured time has expired (in previous example: after 7 days).

Reach out to your Account Manager to set this up.

Expand

title	Is it possible to connect multiple external data sources through the same endpoint in Workplace?

It's possible to re-use the external data source information (Authentication token + URL).

So if devices have the same behavior, but are linked to different external data sources, it’s possible to only set up 1 endpoint in Studio, and have the 2 external data source send data to that same Workplace endpoint.

Info
Within 1 vendor ID, sensor IDs need to be unique and prepended with the vendor ID. Combining device IDs from multiple third parties in 1 External Data Source, raises the potential risk of conflicts.

Expand

title	Is it possible to send data with a timestamp that deviates from today's date?

Technically, Workplace can accept data with timestamps from 5 years in the past and 1 year in the future. But of course this data will not be included in any calculations or live data view. Only time slots for the previous day are calculated. So, even we store the data, it will not be visible anywhere.

So best practice is to just send data with a (near) real time timestamp.

Expand

title	Is it possible to delete an External Data Source?

In Workplace, it’s possible to disable an External Data Source, but you can’t delete. Deletion would impact devices that have a link with this External Data Source.

Troubleshooting

Expand

title	Not getting a 200 status code (indicating succesful connection)?

Make sure the following configuration is in place:

the connection details used in the external data source are the ones provided by Spacewell
verify the authorization code has not been updated / changed in Workplace
adhere to the required supported data types & payload

Expand

title	Successfull connection message, but sensor is not loading any data

Make sure the following configuration is in place:

sensor ID created in Workplace adheres to the described logic, and contains:
- environment tenant ID
- External Data Source ID
- unique_device_id that is mentioned in the payload (in case of 3rd party vendor will need to be provided by the 3rd party)
sensor data is send according to the required https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#Supported-data-types-%26-payload
relevant sensor data channels are enabled for the device on the Spacewell platform

Expand

title	Seeing "Created by Spacewell" and not able to refresh the token or enable/disable the external data source?

See “Legacy Generic End-Point Set-up” chapter below

Expand

title	Not able to refresh the token or enable/disable the external data source?

For security reasons: If a user logs in with a multi-tenant account, they are not able to make any changes to any external data sources.

Legacy Generic End-Point Set-up

In the past, some external data sources were connected to Spacewell through a slightly different format. Because of that, there is a limitation only for the legacy / old generic endpoints:

The old / legacy Generic Endpoints will be shown in Studio with the label 'Created by Spacewell'
User will not be take actions (Refresh Authorization token, Enable / Disable will all be greyed out)
User can only View, and Copy URL / Authorization token.

To Enable / Disable or Refresh authorization token, reach out to your Account Manager.

Search

Live Search

Version	Old Version 40	New Version 41
Changes made by	Julie Isebaert	Julie Isebaert
Saved on	Jun 04, 2024	Sept 11, 2024

Versions Compared

Key

Content

Learning Objectives

How to set up this connection?

Configure Data Payload

Webhooks

Supported data types & payload

Configure the connection between External Data Source and Workplace

Test your setup

Next steps

FAQ

Troubleshooting

Legacy Generic End-Point Set-up

Content Comparison

Versions Compared

Key

Content

Learning Objectives

How to set up this connection?

Configure Data Payload

Webhooks

Supported data types & payload

Configure the connection between External Data Source and Workplace

Test your setup

Next steps

FAQ

Troubleshooting

Legacy Generic End-Point Set-up