Externe gegevensbronnen

Avatar
Laura CARBO

Moeilijkheidsgraad: expert

Inhoud

Leerdoelen

Na het lezen van dit artikel kunt u:

  • Vaststellen welke gegevenstypen worden ondersteund door Spacewell Workplace
  • Een webhook en autorisatietoken configureren om uw externe gegevensbronnen met Workplace te verbinden

Stel dat er al sensoren zijn die gegevens verzamelen in het gebouw en dat u deze gegevens wilt opnemen in het Workplace-IoT-platform. Spacewell biedt een generiek eindpunt (met behulp van webhooks) voor de meeste sensortypen, om sensorgegevens van platforms van derden te integreren, te verwerken en op te slaan.

 

Externe gegevensbronnen voor beginners - een analogie

Aangezien u op deze pagina bent: het lijkt erop dat de sensoren die gegevens naar het Workplace-platform moeten sturen, gegevens verzenden naar een platform of database die niet met Workplace is verbonden. Terwijl u deze pagina doorneemt, zorgen we ervoor dat er een verbinding tussen de platforms wordt ingesteld, dat de verzonden gegevens een indeling hebben waarmee Workplace kan werken en die het kan herkennen.

Het instellen van externe gegevensbronnen en het verzenden van gegevens vanuit een externe database naar het Workplace-platform kan worden vergeleken met: “Een auto arriveert bij een poort. De auto is bekend bij de poortwachter en de persoon in de auto heeft een badge, omdat hij zijn contactpersoon vooraf heeft laten weten dat hij zou komen.”

 

image-20231115-090448.png

 

  1. We willen dat het externe platform gegevens naar Workplace verzendt. Daarom gebruiken we een webhook met HTTP-methode “post”. Dit betekent dat de gegevens door het andere systeem worden gepusht en dat Workplace deze niet ergens vandaan hoeft te halen.
  2. Door een externe gegevensbron in de tenant te maken, creëert u een deur of poort naar het Workplace-platform: de webhook-URL. U ontvangt ook de code om de poort te openen: het autorisatietoken. Door deze informatie aan de eigenaren van de database te verstrekken, kunnen zij de deur bereiken.
  3. Maar zij moeten ons de gegevens aanbieden op een manier die wij kunnen verwerken! Daarom moeten zij zich aan enkele regels houden:
    1. de gegevens die zij ons sturen moeten betekenisvol zijn: Workplace moet iets met die gegevens kunnen doen (bijvoorbeeld deze weergeven op een live plattegrond of in een dashboard). De externe gegevensbron moet de gegevens dus aanleveren in een van de meer dan 10 ondersteunde gegevenstypen.
    2. Het is niet voldoende dat zij ons zomaar wat gegevens sturen. Om die gegevens correct te interpreteren, moeten ze voldoen aan een specifieke (payload)indeling. Zo weten we welk deel van de informatie we moeten interpreteren als apparaat-ID, welk deel als de waarde die we in de Workplace-database moeten opslaan, enzovoort.
  4. Om ervoor te zorgen dat Spacewell weet waar we de gegevens in onze database moeten opslaan, moet de sensor bij ons bekend zijn en aan een locatie zijn gekoppeld. Daarom moet het apparaat in Studio worden geregistreerd. Om het apparaat op het Workplace-platform te registreren, hebt u het volgende nodig:
    1. Apparaattype, dat een vooraf ingestelde reeks gegevenstypen bevat (voor elk gekozen apparaattype wordt een standaardset kanalen ingeschakeld).
    2. Apparaat-ID, die uniek moet zijn.
      1. Om deze ID uniek te maken voor alle tenants, bevat de indeling van de apparaat-ID de tenant-ID
      2. Om deze ID uniek te maken binnen de tenant, bevat de indeling van de apparaat-ID de ID van de externe gegevensbron
    3. Locatiegegevens. Als een sensor niet aan een locatie is gekoppeld, worden de gegevens niet opgeslagen in de Spacewell-database.

 

image-20231115-090448.png
  • het feit dat de auto bij de poort arriveert zonder dat Spacewell iets hoeft te doen, is de webhook
  • het ondersteunde gegevenstype was de instructie om zich bij een specifieke poort te melden
  • het merk en model van de auto vormen de payload, het voertuig dat wordt gebruikt om de gegevens aan te leveren
  • de gegevens bevinden zich in de kofferbak van de auto
  • de sensor-ID is de badge die voor identificatie wordt gebruikt
  • het apparaattype is het poortnummer
  • de poort gaat open dankzij het autorisatietoken

 

Spacewell-consultants die meer willen leren over hoe Spacewell binnenkomende gegevens verwerkt, kunnen Sensorgegevens omgezet in tijdslotgegevens bekijken

 

De sensorleverancier moet voldoen aan de webhook, ondersteunde gegevenstypen en payload van Spacewell.

Info

Binnen één leveranciers-ID moeten sensor-ID's uniek zijn en voorafgegaan worden door de leveranciers-ID.
Het combineren van apparaat-ID's van meerdere derden in één externe gegevensbron verhoogt het risico op conflicten.

 

Hoe stelt u deze verbinding in?

Stappen die op deze pagina worden beschreven:

  1. In de externe database (van de klant of derde partij): configureer de gegevenspayload
  2. Configureer de verbinding tussen externe gegevensbron en Workplace
  3. Ga naar de database en vul de URL en het token in; zorg ervoor dat u de verbinding test
  4. Configureer apparaten op het Workplace-platform
  5. Apparaten verzenden gegevens naar het Workplace-platform

Gegevenspayload configureren

Webhooks

Webhooks bieden een snelle en veilige manier om sensorgegevens betrouwbaar vanuit andere systemen te streamen.
Van de sensorleverancier wordt verwacht dat deze updates naar het Spacewell-eindpunt verzendt.
Het webhook-eindpunt verwacht één HTTP-aanvraag die een afzonderlijk bericht van de sensor vertegenwoordigt.

Ondersteunde gegevenstypen en payload

Voor alle gegevenstypen is het verstandig om te controleren of de gegevens regelmatig worden verzonden; zie Externe gegevensbronnen 

 

Gegevenstypen met betrekking tot ruimtebezetting:

PIR*: ruimtebezetting
Personentelling*: voor het meten van het aantal personen

 

Als uw apparaat voor personentelling meerdere telgebieden kan volgen, kunt u de gegevens van de afzonderlijke telgebieden naar ons verzenden door "<unique_device_id>" te vervangen door "<unique_area_id>".

Puls: voor deurtellers die pulswaarden verzenden
Teller: voor deurtellers die geaccumuleerde waarden verzenden
Voetgangersstroom in-puls**
Voetgangersstroom uit-puls**
Parkeren**

* De kleinste tijdseenheid die door het Workplace-platform wordt geaccepteerd, is seconden. Payloadberichten mogen geen millisecondegegevens bevatten

** Afhankelijk van de betrouwbaarheid van de sensor kunnen gegevens over ruimtebezetting alleen gegevens bevatten die “beweging” bevestigen (aanwezigheid, personentelling, voetgangersstroom in de ene of andere richting, enzovoort), en niet de afwezigheid van beweging… Om dit in het Workplace-platform aan te pakken, is een vervalfunctie geïntroduceerd. Hiermee kan de bezetting/personentelling langer worden gevisualiseerd op de liveplattegronden (voor eindgebruikers) dan de gegevens daadwerkelijk aangeven.

Zie Bewegingssensor voor een voorbeeld van hoe verval werkt

Zie Externe gegevensbronnen  voor een mogelijke oplossing voor gegevenshiaten in de dashboards (gegevens naar tijdsloten kopiëren)

 

Gegevenstypen met betrekking tot comfort:

Temperatuur
Luchtvochtigheid

* De kleinste tijdseenheid die door het Workplace-platform wordt geaccepteerd, is seconden. Payloadberichten mogen geen millisecondegegevens bevatten

 

Gegevenstypen met betrekking tot binnenluchtkwaliteit:

CO2
TVOC (totale vluchtige organische stoffen)
Radon

* De kleinste tijdseenheid die door het Workplace-platform wordt geaccepteerd, is seconden. Payloadberichten mogen geen millisecondegegevens bevatten

 

Gegevenstypen met betrekking tot batterijen:

Batterijpercentage

* De kleinste tijdseenheid die door het Workplace-platform wordt geaccepteerd, is seconden. Payloadberichten mogen geen millisecondegegevens bevatten

 

Info

Het is een goede gewoonte om dit eerst lokaal in een sandboxomgeving te testen

De verbinding tussen externe gegevensbron en Workplace configureren

Toegang verkrijgen

 

  1. Selecteer “Add New”
  2. Tenant-ID wordt ingevuld op basis van de omgeving waarop u bent ingelogd
  3. Vul bij Source ID een unieke naam in die naar uw externe gegevensbron verwijst

Opmerking

Gebruik in het veld Source ID alleen alfanumerieke waarden. De Source ID wordt later gebruikt als onderdeel van de apparaat-ID's.

  1. (Optioneel) Vul een beschrijving in met details over het soort gegevens dat via de externe gegevensbron binnenkomt
  2. Kopieer de verstrekte webhook-URL en het autorisatietoken om de webhook in de externe gegevensbron naar Spacewell Workplace te maken
  3. Zorg ervoor dat uw configuratie is ingeschakeld in Workplace

image-20230901-151124.png

Info

Het is mogelijk om het autorisatietoken in Studio te vernieuwen. Vergeet niet dat dit nieuwe token ook moet worden bijgewerkt op het platform van de derde partij.

Uw configuratie testen

Nadat de webhook in de database van de derde partij is gemaakt met de hierboven verstrekte URL en het token, moet u de verbinding testen.

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

Controleer met een tool zoals Postman of uw configuratie werkt:

  • Als de aanvraag niet succesvol is, retourneert het eindpunt statuscodes 4xx-5xx, afhankelijk van het opgetreden probleem.
  • Als de aanvraag succesvol is, retourneert het eindpunt een 200-statuscode met een lege body.
    • Code 200 bevestigt dat Workplace een bericht in JSON-indeling ontvangt, maar valideert niet of we het bericht kunnen lezen/uitpakken. Raadpleeg bij twijfel het hoofdstuk “Probleemoplossing” hieronder.

image-20230901-153229.png

Volgende stappen

Zie Aangepaste apparaattypen om aangepaste apparaattypen te maken en uw sensoren van derden in Workplace te configureren

Veelgestelde vragen

Wat als de sensor niet regelmatig gegevens verzendt? Is het mogelijk om gegevens naar tijdsloten te kopiëren?

Afhankelijk van het soort sensor verzenden deze mogelijk niet regelmatig heartbeats of gegevens. Als ze gegevens verzenden en vervolgens alleen een bericht sturen wanneer de waarde verandert, krijgt u mogelijk losse stukjes gegevens (bijvoorbeeld één tijdslot van 15 minuten met temperatuurgegevens en de rest van de dag niets). Dit kan verwarrend zijn wanneer u de dashboards probeert te lezen.

Om dit te omzeilen, kunt u ervoor kiezen om Spacewell de gegevens te laten kopiëren, op het niveau van het generieke eindpunt/apparaattype, gedurende de gewenste tijdsduur.

Voor het sensortype "Generic PIR" kunnen we bijvoorbeeld "kopiëren naar verdere tijdsloten" instellen. Deze waarde zou geldig zijn voor alle waarden van Generic PIR-sensoren die vanuit uw tenant naar ons komen. De gegevens worden uiteraard alleen gekopieerd totdat er opnieuw nieuwe gegevens binnenkomen. Als er dus op maandag om 9.00 uur een waarde binnenkomt, de configuratie "7 dagen kopiëren" aangeeft en er op woensdag om 8.00 uur een nieuwe waarde binnenkomt, wordt de nieuwe waarde vanaf woensdag 8.00 uur gedurende 7 dagen gebruikt, of totdat er een nieuwe waarde binnenkomt.

Info

Bijgevolg visualiseert of rapporteert Workplace alleen dat een sensor GEEN gegevens verzendt nadat de geconfigureerde tijd is verstreken (in het vorige voorbeeld: na 7 dagen).

Neem contact op met uw Account Manager om dit in te stellen.

Is het mogelijk om meerdere externe gegevensbronnen via hetzelfde eindpunt in Workplace te verbinden?

Het is mogelijk om de informatie van de externe gegevensbron (authenticatietoken + URL) opnieuw te gebruiken.

Als apparaten dus hetzelfde gedrag vertonen, maar aan verschillende externe gegevensbronnen zijn gekoppeld, is het mogelijk om slechts één eindpunt in Studio in te stellen en de twee externe gegevensbronnen gegevens naar hetzelfde Workplace-eindpunt te laten verzenden.

Info

Binnen één leveranciers-ID moeten sensor-ID's uniek zijn en voorafgegaan worden door de leveranciers-ID.
Het combineren van apparaat-ID's van meerdere derden in één externe gegevensbron verhoogt het risico op conflicten.

Is het mogelijk om gegevens te verzenden met een tijdstempel die afwijkt van de datum van vandaag?

Technisch gezien kan Workplace gegevens accepteren met tijdstempels van 5 jaar in het verleden en 1 jaar in de toekomst. Deze gegevens worden uiteraard niet opgenomen in berekeningen of de livegegevensweergave. Alleen tijdsloten voor de vorige dag worden berekend. Dus hoewel we de gegevens opslaan, zijn ze nergens zichtbaar.

Het is daarom een goede gewoonte om gegevens te verzenden met een tijdstempel in (bijna) realtime.

Is het mogelijk om een externe gegevensbron te verwijderen?

In Workplace is het mogelijk om een externe gegevensbron uit te schakelen, maar u kunt deze niet verwijderen. Verwijdering zou gevolgen hebben voor apparaten die aan deze externe gegevensbron zijn gekoppeld.

Bij het combineren van gegevens uit externe bronnen met automatiseringen

Sensoren die zijn gekoppeld aan de locatie(s) waarop een automatisering van toepassing is, moeten ten minste elke 24 uur een heartbeat leveren; zie Workplace-automatisering

Probleemoplossing

Geen 200-statuscode ontvangen (die op een succesvolle verbinding wijst)?

Zorg ervoor dat de volgende configuratie aanwezig is:

  • de verbindingsgegevens die in de externe gegevensbron worden gebruikt, zijn de gegevens die door Spacewell zijn verstrekt
  • controleer of de autorisatiecode niet is bijgewerkt/gewijzigd in Workplace
  • voldoe aan de vereiste ondersteunde gegevenstypen en payload
Succesvol verbindingsbericht, maar sensor laadt geen gegevens

Code 200 bevestigt dat Workplace een bericht in JSON-indeling ontvangt, maar valideert niet of we het bericht kunnen lezen/uitpakken.

Zorg ervoor dat de volgende configuratie aanwezig is:

  • de in Workplace aangemaakte sensor-ID volgt de beschreven logica en bevat:
    • tenant-ID van de omgeving
    • ID van de externe gegevensbron
    • unique_device_id die in de payload wordt vermeld (bij een leverancier van derden moet deze door de derde partij worden verstrekt)
  • sensorgegevens worden verzonden volgens de vereiste Externe gegevensbronnen, inclusief maar niet beperkt tot:
    • we verwachten dat de tijdstempel tijdzonegegevens bevat volgens ISO 8601 voor datum en tijd. Hoewel Workplace met tijdzone Z werkt, kunnen andere tijdzones worden geaccepteerd als ze correct zijn opgemaakt.
    • De kleinste tijdseenheid die door het Workplace-platform wordt geaccepteerd, is seconden. Payloadberichten mogen geen millisecondegegevens bevatten.
    • JSON-gegevens (namen en waarden) moeten tussen dubbele aanhalingstekens ("") worden geplaatst.
  • relevante sensorgegevenskanalen zijn ingeschakeld voor het apparaat op het Spacewell-platform
U ziet "Created by Spacewell" en kunt het token niet vernieuwen of de externe gegevensbron niet in- of uitschakelen?

Zie het onderstaande hoofdstuk “Configuratie van legacy generiek eindpunt”

U kunt het token niet vernieuwen of de externe gegevensbron niet in- of uitschakelen?

Om veiligheidsredenen kunnen gebruikers die inloggen met een account voor meerdere tenants geen wijzigingen aanbrengen in externe gegevensbronnen.

Configuratie van legacy generiek eindpunt

In het verleden werden sommige externe gegevensbronnen via een iets andere indeling met Spacewell verbonden. Daarom geldt er alleen voor de legacy/oude generieke eindpunten een beperking:

  1.  De oude/legacy generieke eindpunten worden in Studio weergegeven met het label 'Created by Spacewell'
  2. De gebruiker kan geen acties uitvoeren (Autorisatietoken vernieuwen, Inschakelen/Uitschakelen worden grijs weergegeven)
  3. De gebruiker kan alleen de URL/het autorisatietoken bekijken en kopiëren.

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

image-20230912-065645.png

 

 

 

Artikelen in deze sectie