Versions Compared

Version Old Version 34 New Version 35
Changes made by

Julie Isebaert

Julie Isebaert

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Difficulty: expert

Content

Table of Contents
minLevel1
maxLevel1

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
titleExternal 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 /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:

  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.

Supported data types & payload

Space occupancy related data types:

Expand
titlePIR: space occupancy
Code Block
languagejson
{
"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
titleHeadcount: for measuring number of people
Code Block
languagejson
{
“device”: "<unique_device_id>", // string: unique id of the device
“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
}
Expand
titlePulse: for door counters sending pulse values
Code Block
languagejson
{
“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
titleCount: for door counters sending accumulated values
Code Block
languagejson
{
“device”: "<unique_device_id>", // string: unique id of the device
“type”: "count", // 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
titlefootfallFootfall-in pulse
Code Block
languagejson
{
“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
titleFootfall-out pulse
Code Block
languagejson
{
“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
titleParking
Code Block
languagejson
{
“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
}

Comfort related data types:

Expand
titleTemperature
Code Block
languagejson
{
“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
titleHumidity
Code Block
languagejson
{
“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
titleCO2
Code Block
languagejson
{
“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
titleTVOC (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
titleRadon
Code Block
languagejson
{
“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

}

Configure the connection between External Data Source and Workplace

How to access

  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

Note

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

  1. (Optional) Fill in a description, detailing what kind of data will come through the external data source

  2. Copy the provided webhook URL + Authorization token to create the webhook in the external data source towards Spacewell Workplace

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

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.

Configure the sensors in Workplace

Prerequisites for this step:

  • have the confirmation that the test was successful (endpoint returns 200 status codewith an empty body)

  • have the confirmation which data type will be used to convey the data

  • have the list of device IDs that will send data from the External Data Source to Workplace platform

  1. Go to your environment (https://studio.cobundu.com ) and log in

  2. Select the location, and manually add a sensor via "Add New Device"

  3. Select the (most relevant) Device Type "Generic …” (eg for PIR: "Generic PIR") from the drop-down list. As per the chosen DeviceType, a default set of channels is enabled

    1. If a device is able to gather data on a channel, that is not part of the DeviceTypes' default set of channels : it’s possible to manually add these in Advanced*

  4. Fill in the Device ID, using the tenant ID and source ID available in Settings > External Data Sources. Adhere to the format <tenant_id>-<source_id>|<device_id>

Expand
titleExample device ID

for example

  • if you want to configure a sensor with ID “123” (unique_device_id that will be mentioned in the payload; in case of 3rd party vendor will need to be provided by the 3rd party)

  • in an environment with tenant ID “spacewell”

  • where an External Data Source with source ID “testgeneric” has been set up

the Spacewell Device ID will be

“spacewell-testgeneric|123"

  1. Give a meaningful name (eg customer_floor number_area) in Device Name.

  2. Location will be filled in based on your pre-selection in the location tree

For more information on how to add multiple new devices to Studio, check out Configure devices (add, remove, import/export).

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.

* If a device is able to gather data on a channel, that is not part of the DeviceTypes' default set of channels : it’s possible to manually add these in Advanced

Image Added

  1. Select the relevant Sensor Type from the drop-down

  2. Fill in the “channel” value as mentioned in the https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#Supported-data-types-%26-payload

Expand
titleConcrete example to set up a device for which there is no Generic DeviceType available

In this example, we’re setting up a sensor that will provide data on footfall (sending data each time a person crosses a (virtual) line in one or in the other direction).

  1. Select the DeviceType that most closely describes the device (in this example we could use “Generic Pulse”

  2. Fill in Device ID, a meaningful name, location etc as mentioned above

  3. Open the “Advanced” section

  4. Delete any sensor types that are selected by default but are not relevant for your sensor

  5. Select “Add new sensor” and add as many new sensor types as relevant for your sensor, in this case:

    1. Sensor type “Footfall (in)”

    2. Sensor type “Footfall (out)”

  6. Fill in the Channel with the information “type” value as mentioned in the https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#Supported-data-types-%26-payload

Image Added

Image Added

FAQ

Expand
titleWhat 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 us 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
titleIs 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.

Troubleshooting

Expand
titleNot 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
titleSuccessfull connection message, but sensor is not loading any data

Make sure the following configuration is in place:

Expand
titleSeeing "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
titleNot 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:

  1.  The old / legacy Generic Endpoints will be shown in Studio with the label 'Created by Spacewell'

  2. User will not be take actions (Refresh Authorization token, Enable / Disable will all be greyed out)

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