miner:integration:proptechos [Orbiq wiki]

Denna sida är skrivskyddad. Du kan titta på källkoden, men inte ändra den. Kontakta administratören om du anser att du bör kunna ändra sidan.
{{tag>miner rec "real estate core" proptechOs}}
====== Dataöverföring till/från ProptechOS via RealEstateCore ======
Miner kan användas för att föra över data som läses in via strömmande eller pollande indataanslutningar, till [[https://proptechos.com/|ProptechOS]] via formatet [[https://www.realestatecore.io/|REC (RealEstateCore)]]. Du kan läsa mer om REC [[https://www.realestatecore.io/introduction/|här]].
På denna sida kan du läsa hur du ställer in en anslutning mot ProptechOS för provisionering av devices, för överföring av strömmande data och för inställning av överskrivningar som initieras från ProptechOS.

Överföring av data till ProptechOS kräver att data provisioneras enligt API:erna som föreskrivs av Real Estate Core (REC). Detta innebär att datapunkter (items) i minerjobb behöver förses med med metadata (attributes) som beskriver dem på ett sådant sätt att ProptechOS kan hantera dem och knyta dem till fysiska sensorer. 

För att en datapunkt (item i ett minerjobb, motsvarande Sensor eller Actuator inom REC3.2) ska kunna provisioneras till en REC-graf, behöver ett antal egenskaper anges och i många fall behöver även flera objekt (Devices) och relationer mellan befintliga objekt skapas inom REC-grafen. Miner hanterar samtliga egenskaper och objekt i form av Attribut som anges på datapunkten (Item). Konfigurationen av attribut kan ske via Miners webbgränssnitt eller genom export och import av CSV-filer från Miner till ett externt redigeringsverktyg (exempelvis MS Excel).

Inom REC v3.2 kan datapunkter (sensors, actuators) organiseras i en hierarki av Devices. Miner stödjer en organisering av datapunkter (Items) i två nivåer som vi kallar för Device (underliggande nivå) och SuperDevice (överliggande nivå). Användaren kan antingen själv ange nivåerna och benämna enheterna (PopularName, Littera), eller så kan Miner gruppera datapunkterna i två nivåer beroende av värden för andra obligatoriska Attributes.

==== Attribut som kan förekomma vid provisionering ====
Tabellen nedan beskriver de attribut som kan förekomma för datapunkter i minerjobb, i de fall där integration sker mot någon plattformslösning via REC 3.2. Vissa av attributen anges av användaren, medan andra sätts av Miner i anslutning till provisioneringen och kan användas för senare referens och felsökning. De REC-specifika attributen börjar med prefixen "rec:".

Förutom de rec-specifika attributen, behöver användaren ange ett antal obligatoriska attribut för samtliga items som ska provisioneras till ProptechOS. Anledningen till detta framgår av tabellen nedan.
  * building
  * equipment
  * system

Användaren kan lägga även lägga till egna attribut vid behov. Alla attribut av typen Constant eller Dynamic, som inte är bland de REC-specifika attributen nedan (se attributen vars namn börjar med rec:), kommer att provisioneras till ProptechOS som så kallad "Source information". Det gäller även de obligatoriska attributen "building", "equipment", "system". Om användaren inte vill att dessa attribut ska synas i ProptechOS som "Source information" och ej heller skickas till andra OutputConnections för jobbet, kan de markeras som "Comments" för att stanna lokalt i Miner. REC-specifika attribut som markeras som Constant eller Dynamic, kommer att skickas till andra OutputConnections för jobbet, men inte tas upp under "Source information" inom ProptechOS.

Tabellen nedan anger även hur attributen sätts i grundutförandet, det vill säga om typen är "Comment" eller "Constant". Som vi nämnde ovan, kan användaren ändra typen beroende av om de ska skickas till mottagande system eller ej.

^ Attribut                                         ^ Obligatorisk  ^ [[miner:anvandning:miner:datapunkter#olika_typer_av_attributmetadata|Typ]] (skapas som)  ^ Beskrivning  ^                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        
| building                                         | Ja            | Constant          | Beteckning/benämning för aktuell byggnad (ex: "Skatan1" eller "5400"). Används för att skapa en hierarki av Devices och SuperDevices.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| equipment                                        | Ja            | Constant          | Beteckning/benämning för aktuell utrustning (ex: "GT11"). Används för att skapa en hierarki av Devices och SuperDevices.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| system                                           | Ja            | Constant          | Beteckning/benämning för aktuellt system (ex: "LB01", "RUM", "Elmätning"). Används för att skapa en hierarki av Devices och SuperDevices.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| rec:Device.Alias                                 |               | Constant          | Skapas av Miner vid provisionering, byggs genom att ange Miners "Base-URL" /item/uuid-för-datapunkten-i-miner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| rec:Device.Class                                 |               | Comment           | Skapas av Miner vid provisionering. Möjliga klasser: Sensor, Actuator. Klassen avgörs av egenskapen i datapunkten (dataAccess: r => Sensor, rw => Actuator)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| rec:Device.hasDefaultActuationInterface.Id       |               | Comment           | Skapas av Miner vid provisioneringen, för Actuators för att identifiera tillåtna värden som skickas till/från denne.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| rec:Device.Id                                    |               | Comment           | Skapas av Miner vid lyckad provisionering av Device.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| rec:Device.isMountedInBuildingComponent.Id       | Ja            | Constant          | Obligatoriskt, anges av användaren                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| rec:Device.Littera                               | Ja            | Constant          | Obligatoriskt, kan anges av användaren. Default: samma värde som för orbiq_tag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| rec:Device.MeasurementUnit                       |               | Constant          | Frivillig                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| rec:Device.PlacementContext                      |               | Constant          | Frivillig                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| rec:Device.PopularName                           | Ja            | Constant          | Obligatoriskt, kan anges av användaren. Default: samma värde som för orbiq_tag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| rec:Device.QuantityKind                          | Ja            | Constant          | Obligatoriskt, anges av användaren                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| rec:SuperDevice.Alias                            |               | Constant          | Skapas av Miner vid provisionering, byggs genom att ange Miners "Base-URL" /connection/uuid-för-connection-i-miner/Superdevice.Littera                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| rec:SuperDevice.Id                               |               | Comment           | Skapas av Miner vid lyckad provisionering av SuperDevice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rec:SuperDevice.isMountedInBuildingComponent.Id  |               | Comment           | Skapas av Miner vid provisionering. Den tar samma värde som Devices isMountedInBuildingComponent.id. Om flera värden, så tar den det första.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| rec:SuperDevice.Littera                          | Ja            | Constant          | Obligatoriskt, kan anges av användaren. Default: byggs med hjälp av värden för "building" - "system" - "equipment"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| rec:SuperDevice.PopularName                      | Ja            | Constant          | Obligatoriskt, kan anges av användaren. Default: byggs med hjälp av värden för "building" - "system" - "equipment"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| rec:Version                                      |               | Comment           | Skapas av Miner, för att ange vilka värdelistor som används vid provisioneringen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

===== Processbeskrivning =====
Integration mot ProptechOS kan ske enligt två scenarion:
  * Miner ska provisionera och överföra mätdata
  * Provisionering är redan gjord och miner ska endast överföra mätdata.

Nedan följer en guide där provisioneringen sker i Miner.

Ett dataöverföringsjobb till ProptechOS kräver fler steg än överföring till exempelvis Orbiq. Användaren:
  * Skapar anslutning mot datakällan från vilken data skall hämtas
  * Skapar en anslutning mot ProptechOS för slutlig dataöverföring
  * Skapar en MQTT anslutning för att kunna föra över uppmätt data till ProptechOS i rätt format och även ta emot överskrivningar från ProptechOS
  * Skapar ett överföringsjobb från datakällan till MQTT-anslutningen
  * Laddar värdelistor med förbestämda attribut från ProptechOS-anslutningen
  * Taggar upp valda datapunkter med attribut från de laddade värdelistorna
  * Skapar ett grafjobb där jobbet mot datakällan väljs som input och ProptechOS-anslutningen väljs som output
  * Startar grafjobbet för att provisionera datapunkterna som valdes i jobbet mot datakällan
  * Startar jobbet mot datakällan för att skicka upp data till ProptechOS

Nedan redovisas en detaljerad beskrivning av de olika arbetsmomenten:

==== Inställning av anslutning mot ProptechOS för överföring av strömmande data ====
Miner kan användas för att registrera nya komponenter (REC:Device, REC:Sensor, REC:Actuator) via ProptechOS:s provisioneringsAPI, i enlighet med RealEstateCore (v3.2) och koppla dem till rätt zon eller rum (REC:BuildingComponent), inför att den börjar strömma data till API:et för strömmande data.

En anslutning mot ProptechOS upprättas för överföring av provisioneringsdata, samt för att hämta värdelistor för standardiserade attribut utifrån den version som väljs.

Skapa en ProptechOS-anslutning enligt att följa stegen nedan:

  *Skapa en ny anslutning av ProptechOS-typ.


{{:integrationer:screenshot_2025-02-14_130406.png?600|}}

  * Fyll i korrekt information för anslutning till ProptechOS. Ange rec3.2 som version.

{{:integrationer:screenshot_2025-02-14_125633.png?600|}}

===== Inställning av MQTT-anslutning för överföring av data till ProptechOS ======
Överföring av data från källsystemet till ProptechOS sker genom MQTT-protokoll. 

  *Som användare skapar du därför en "IoT Hub MQTT"-anslutning som används för dataöverföring:

{{:integrationer:screenshot_2025-02-14_133227.png?600|}}

  *Var noggrann med att all data fylls i korrekt och att alla obligatoriska fält märkta * är ifyllda.
===== Inställning av anslutning mot källsystem för avläsning av data =====
  * Skapa en anslutning mot det källsystem vars data du önskar överföra till ProptechOS.
  * Var noggrann med att all data fylls i korrekt och att alla obligatoriska fält märkta * är ifyllda.
===== Konfigurera jobb för val och inställning av datapunkter för överföring av mätvärden =====
När alla anslutningar som krävs för provisionering av datapunkter och överföring av mätvärden är skapade är det dags att skapa ett jobb för dataöverföring från källsystemet till ProptechOS.

  * Skapa ett jobb mot den källsystemsanslutning du skapade i tidigare steg. I exemplet nedan har en anslutning mot ett Larmia-system valts.

{{:integrationer:screenshot_2025-02-14_134153.png?600|}}

  * Under "indata" ska källsystemets anslutning väljas.

  * Under "utdata" väljs den "IoT Hubb MQTT"-anslutning som skapades tidigare väljas. Detta är för att dataöverföringen sker genom MQTT-protokollet.

  * I nästa steg kommer utdata-anslutningen att konfigureras ytterligare. 

{{:integrationer:screenshot_2025-02-14_141624.png?600|}}

  * För överföring mot ProptechOS ska Rec 3.2 väljas under JSON Schema.

  * När all information är ifylld trycker du på "Nästa".
==== Ladda lista med byggnadskomponenter inför inställning av provisioneringen ====
När MQTT-anslutningen har konfigurerats väljer du vilka datapunkter från källsystemet du önskar ta med i jobbet. Därefter ska du välja en Proptech-anslutning att ladda värdelistor från. 

  *Börja med att klicka i check-rutan märkt ”Hämta metadata-lista för jobbet”:

{{:integrationer:screenshot_2025-02-17_114049.png?600|}}

  *Välj därefter en ProptechOS-anslutning att hämta värdelistor för och tryck ”Lägg till”:

{{:integrationer:screenshot_2025-02-17_114325.png|}}

  *Därefter kan du klicka på den valda anslutningen för att expandera vyn och visa konfigurationen av listorna:

{{:integrationer:screenshot_2025-02-17_121909.png|}}

För listorna som visas gäller detta:
Quantity Kind, Placement Context och Measurement unit behöver inte nödvändigtvis konfigureras vidare. Listorna kan dock laddas ner i CSV-format och fyllas i i valfritt program som kan hantera CSV-filer. De ifyllda listorna kan sedan laddas upp igen.
RealEstate, Building och BuidlingComponents måste konfigureras vidare. Detta görs enligt följande:

  *Börja med att klicka på ”Ladda fastigheter”. När listan är färdigladdad väljer du den fastighet som är aktuell för jobbet.

  *Därefter laddar du byggnader genom att klicka på ”Ladda byggnader”. Välj aktuell byggnad när listan är färdigladdad och tryck sedan på ”Ladda byggnadskomponenter”.
  
  
  *När byggnadskomponenterna är laddades indikeras detta av en grön bock:

{{:integrationer:screenshot_2025-02-17_122052.png|}}

=== Ställ in nödvändig metadata för valda datapunkter ===
När byggnadskomponenterna är laddade har alla obligatoriska attribut laddats och datapunkterna är redo för konfigurering.

Innan en datapunkt har konfigurerats enligt värdelistorna visar den en varning om att den har ofärdiga attribut. Så länge denna varning visas kan inte datapunkten provisioneras.

{{:integrationer:screenshot_2025-02-17_122726.png?1000|}}
 
Påbörja konfigurering av en datapunkt genom att klicka på den i listan. 

I datapunktsvyn ser du de attribut som ska fyllas i. Vissa attribut är markerade med en röd cirkel. Dessa är obligatoriska och ett värde måste anges. Vissa attribut är markerade med en svart cirkel. Dessa är inte obligatoriska och kan lämnas tomma, men de kan inte tas bort.
Övriga attribut är standardattribut som läggs till av anslutningen själv. Dessa kan tas bort eller lämnas tomma.

{{:integrationer:screenshot_2025-02-17_122541.png?1000|}}

När attributen är ifyllda sparar du datapunkten för att fortsätta med de andra datapunkterna. I listan kommer du se att varningen om att datapunkten har ofärdiga attribut har försvunnit från den datapunkten du nyss fyllde i.
Notera att du inte behöver fylla i attribut för alla datapunkter på en gång. Du kan spara jobbet utan att konfigurera datapunkternas attribut för att senare fylla i attributen antingen genom Miners interface eller genom att importera datapunkter via CSV.

Oavsett hur du väljer att konfigurera datapunkterna måste du klarmarkera en datapunkt för att denna ska tas med i dataöverföringen när jobbet körs. Klarmarkering av en datapunkt kan endast göras om samtliga av datapunktens obligatoriska attribut har fyllts i. För att klarmarkera en datapunkt, klicka i checkboxen till vänster i datapunktsraden och klicka på knappen "Växla klarmarkering" som dyker upp överst på sidan. En klarmarkerad datapunkt markeras med grön färg.

{{:integrationer:screenshot_2025-02-17_123135.png?1000|}}

När du är nöjd med konfigurering och klarmarkering av jobbets datapunkter sparar du jobbet. Som nämns ovan kan du nu fortsätta att konfigurera jobbet genom interface i Miner eller genom att importera CSV-fil.

===== Konfigurera jobb för provisionering av datapunkter inom ProptechOS =====
När jobbet mot datakällan har skapats och datapunkterna har konfigurerats och märkts upp med attribut för ProptechOS är det dags att skapa ett jobb för provisionering mot ProptechOS.

Skapa ett nytt jobb och välj ”Grafjobb” som jobbtyp:

{{:integrationer:screenshot_2025-02-17_123428.png?600|}}

Välj en ProptechOS-anslutning som utdata.

I nästa steg ska ProptechOS-anslutningen konfigureras. Fyll i de obligatoriska fälten och tryck ”Nästa”.

I datapunktsvyn ska du välja det källsystemjobb som du skapade i tidigare steg.

Spara jobbet.

===== Starta jobbet för provisionering =====
Nu är allting uppsatt för att påbörja provisionering av datapunkter samt att därefter påbörja dataöverföring mot ProptechOS.

Börja med att starta grafjobbet. 

{{:integrationer:screenshot_2025-02-17_123704.png?800|}}

I listvyn kan du se att provisioneringen påbörjas och hur långt den har kommit. 

Medan provisionering pågår blir förloppsindikatorn gul. 

Om ett fel i provisioneringen uppstår, exempelvis om någon datapunkts attribut inte fyllts i korrekt, kommer detta att indikeras av förloppsindikatorns röda färg. 

Vidare kan man gå in i jobbet och se vilken av datapunkterna som felar och varför.

{{:integrationer:screenshot_2025-02-17_123812.png?800|}}

När alla datapunkter är provisionerade indikeras detta av att förloppsindikatorns färg blir grön. 

===== Starta jobbet för dataöverföring =====
När provisioneringen är färdig har alla datapunkter i jobbet knutits till en punkt i ProptechOS och dataöverföring från källdatajobbet kan påbörjas. Detta görs enkelt genom att starta källdatajobbet.

Notera att det går att starta källdatajobbet innan provisioneringsjobbet startas. Då kommer ingen data att överföras till ProptechOS innan datapunkterna har provisionerats. 

Det rekommenderas att låta provisioneringen bli klar innan dataöverföringen startas.