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

« Previous Version 39 Next »

Difficulty: expert

Content

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.

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

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

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

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:

 PIR*: space occupancy
{
"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
}
 Headcount*: for measuring number of people
{
“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
}
 Pulse: for door counters sending pulse values
{
“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
}
 Counter: for door counters sending accumulated values
{
“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
}
 Footfall-in pulse*
{
“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
}
 Footfall-out pulse*
{
“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
}
 Parking*
{
“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:

 Temperature
{
“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
}
 Humidity
{
“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:

 CO2
{
“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
}
 TVOC (Total volatile organic compounds)
{
“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
}
 Radon
{
“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

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

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.

Configure the sensors in Workplace

Prerequisites for this step:

  • have the confirmation that the test was successful (endpoint returns 200 status code with 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>

 Example 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, and export).

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

  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

 Concrete 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

FAQ

 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.

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.

 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.

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

 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

 Successfull connection message, but sensor is not loading any data

Make sure the following configuration is in place:

 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

 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:

  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

  • No labels