DifficultyMoeilijkheidsgraad: expert

Stel dat er al sensoren zijn die gegevens verzamelen in het gebouw en u wilt deze gegevens opnemen in het Workplace IOT-platform. Spacewell biedt een generiek eindpunt (met webhooks) voor het grootste deel van zijn soorten sensorgegevensom sensorgegevens van platforms van derden te integreren, verwerken en op te slaan.

Expand
title Externe gegevensbronnen voor beginners - een analogie
Nu u toch op deze pagina bent: het lijkt erop dat de sensoren die gegevens naar het Workplace platform sturen, gegevens naar een platform of database sturen die niet met Workplace is verbonden. Op deze pagina zullen we ervoor zorgen dat er een verbinding is tussen de platforms en dat de gegevens worden verzonden in een formaat waarmee Workplace kan werken en dat het weet hoe het te identificeren. Het opzetten van externe gegevensbronnen en het verzenden van gegevens van een externe database naar het Workplace platform kan worden vergeleken met "Er komt een auto aan bij een poort. De auto is bekend bij de poortwachter en de persoon in de auto heeft een badge, omdat hij zijn contactpersoon van tevoren heeft verteld dat hij eraan kwam." Image Added We willen dat het externe platform gegevens verzenden naar Workplace, daarom gebruiken we webhook met HTTP-methode "post". Dit betekent dat de gegevens geduwd door het andere systeem, en Workplace hoeft niet te trek het ergens vandaan. Door een Externe gegevensbron te maken in de tenant, maak je een deur of poort naar het Workplace platform: de URL van de Webhook. U ontvangt ook de code om de poort te openen: het autorisatietoken. Door deze informatie aan de eigenaars van de database te geven, kunnen ze nu de deur bereiken. Maar ze moeten ons de gegevens presenteren op een manier die we kunnen consumeren! Zodat ze zich aan enkele regels moeten houden: de de gegevens die ze ons sturen moeten betekenisvol zijn: Workplace moet iets met die gegevens kunnen doen (bijvoorbeeld ze presenteren op een live plattegrond of in een dashboard). Zodat de Externe Gegevensbron de gegevens moet leveren in een van de meer dan 10 ondersteunde gegevenstypen. Het is niet genoeg dat ze ons zomaar wat gegevens voor de voeten werpen. Om correct interpreteren die gegevens moeten voldoen aan een specifiek (payload) formaat. Op deze manier weten we welk deel van de informatie we moeten interpreteren als de apparaat-ID, welk deel als de waarde die we moeten opslaan in de Workplace database, enz. Voor Spacewell om te weten waar we de gegevens moeten opslaan in onze database, moet de sensor bij ons bekend zijn en gekoppeld zijn aan een locatie. Daarom moet het apparaat worden geregistreerd in Studio. Om het apparaat in Workplace Platform te registreren, hebt u het volgende nodig: Type apparaatdie eigenlijk een voorinstelling van gegevenstypes bevat (per gekozen DeviceType wordt een standaardset kanalen ingeschakeld). Apparaat-IDdie uniek moet zijn. Om deze ID uniek te maken voor alle huurders, bevat de indeling van de apparaat-ID de huurder-ID Om deze ID uniek te maken binnen de tenant, bevat de indeling van de apparaat-ID de Externe gegevensbron-ID Informatie over de locatie. Als een sensor niet is gekoppeld aan een locatie, worden de gegevens niet opgeslagen in de Spacewell-database. Image Added het feit dat de auto aankomt bij de poort zonder dat Spacewell iets hoeft te doen, is de webhook het ondersteunde gegevenstype was de instructie om te presenteren bij een specifieke poort het merk en model van de auto is de payload, het voertuig dat wordt gebruikt om de gegevens te presenteren de gegevens liggen in de kofferbak van de auto de sensor-ID is de badge die wordt gebruikt voor identificatie het apparaattype is het poortnummer de poort is open dankzij het autorisatietoken Spacewell consultants die meer willen weten over hoe Spacewell omgaat met gegevens die binnenkomen, kunnen kijken op /wiki/spaces/WM/pages/492237

The sensor vendor needs to comply with the De sensorverkoper moet voldoen aan de Spacewell webhook, supported data types & ondersteunde gegevenstypen en 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.

Hoe stel ik deze verbinding in?

Stappen beschreven op deze pagina:

1. In de externe database (klant of derde partij): Gegevenslading configureren

2. De verbinding tussen Externe gegevensbron en Workplace configureren

3. Ga naar de database en vul URL en token in, zorg ervoor dat je de verbinding test

4. Apparaten configureren op het Workplace platform

5. Apparaten sturen gegevens naar Workplace platform

Gegevenslading configureren

Webhooks

Webhooks bieden een snelle en veilige manier om betrouwbaar sensorgegevens van andere systemen door te sturen.
Van de sensorprovider wordt verwacht dat hij updates post naar het Spacewell eindpunt.
Het webhook-eindpunt verwacht een enkel HTTP-verzoek dat een afzonderlijk bericht van de sensor vertegenwoordigt.

• De webhook URL:

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

  • USVS: <https://bohemian.us1.cloud.cobundu.com/generic/<sensor_vendor>verkoper>/data>

• Gebruikte HTTP method used-methode: POST

• HTTP-headers:

  • AuthorizationMachtiging: Bearer Drager <token>

  • Content-TypeInhoudstype: applicationtoepassing/json

Supported data types & payload

Ondersteunde gegevenstypen en payload

Voor alle gegevenstypen is het zinvol om te controleren of gegevens regelmatig worden verzonden of niet; zie https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

Space occupancy related data typesDatatypes met betrekking tot ruimtebezetting:

{
"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
}

{
“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
}

{
“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
}

{
“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
}

{
“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
}

{
“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
}

{
“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 Afhankelijk van de betrouwbaarheid van de sensor kan het zijn dat de ruimtebezettingsgegevens alleen gegevens bevatten over bevestiging "beweging" (aanwezigheid, aantal hoofden, voetstappen in de ene of de andere richting enz. afwezigheid van beweging... Om dit in het Workplace platform aan te pakken, is er een vervalfunctie geïntroduceerd die het mogelijk maakt om de bezetting/headcount op de live (eindgebruiker gerichte) plattegronden langer te visualiseren dan wat de gegevens ons werkelijk vertellen.

Voor een voorbeeld van hoe verval werkt, zie 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 Zie voor een mogelijke oplossing voor gegevenslacunes in de dashboards (gegevens kopiëren in tijdslots) https://spacewell.atlassian.net/wiki/spaces/KB/pages/5242896/External+Data+Sources#FAQ

Comfort related data typesComfortgerelateerde gegevenstypen:

{
“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
}

{
“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 typesAan binnenluchtkwaliteit gerelateerde gegevenstypen:

{
“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
}

{
“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
}

{
“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

De verbinding tussen Externe gegevensbron en Workplace configureren

Hoe krijg ik toegang

• Ga naar https://studio.cobundu.com/

• Login with your credentials

• Select Integrations > External Data Sources in the Inloggen met je gegevens

• Selecteer Integraties > Externe gegevensbronnen in de Studio 2.0-interface

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

Make sure to enable your setup

1. Selecteer "Nieuw toevoegen".

2. Huurder-ID wordt ingevuld op basis van de omgeving waarop je bent ingelogd

3. Vul Source ID in met een unieke naam, verwijzend naar uw externe gegevensbron

4. (Optioneel) Vul een beschrijving in, waarin staat wat voor soort gegevens via de externe gegevensbron komen

5. Kopieer de URL van de webhook + het autorisatietoken om de webhook aan te maken in de externe gegevensbron naar Spacewell Workplace.

6. Zorg ervoor dat uw installatie is ingeschakeld 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.

Image Removed

Check below chapter “Troubleshooting” in case of doubts.

Next steps

Test je opstelling

Zodra de webhook is aangemaakt in de database van de 3e partij met de bovenstaande URL en token, moet u de verbinding testen.

Deze stap moet worden uitgevoerd door de partij die gegevens naar Spacewell Workplace wil verzenden.

Controleer met een programma als Postman of je opstelling werkt:

• Als het verzoek niet succesvol is, retourneert het eindpunt 4xx-5xx statuscodes afhankelijk van de opgetreden kwestie.

• Als het verzoek succesvol is, retourneert het eindpunt 200 statuscode met een leeg lichaam.

Image Added

Raadpleeg bij twijfel het hoofdstuk "Problemen oplossen" hieronder.

Volgende stappen

Zie voor het maken van aangepaste apparaattypen en het configureren van sensoren van derden in Workplace Custom Device Types

FAQ

Make sure the following configuration is in place:

Troubleshooting

Problemen oplossen

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.

Image Removed

Search

Generieke eindpuntinstelling

In het verleden waren sommige externe gegevensbronnen via een iets ander formaat verbonden met Spacewell. Hierdoor is er alleen een beperking voor de legacy / oude generieke eindpunten:

1. De oude / legacy Generic Endpoints worden in Studio getoond met het label 'Gemaakt door Spacewell'.

2. De gebruiker kan geen acties ondernemen (Vernieuw Autorisatie token, Inschakelen / Uitschakelen worden allemaal grijs weergegeven)

3. Gebruiker kan alleen URL/autorisatietoken bekijken en kopiëren.

Neem contact op met je Account Manager om het autorisatietoken in/uit te schakelen of te vernieuwen.

Image Added

Zoek op