miner:integrationer:systemintegration [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.
====== Systemintegration ======

Den här sidan beskriver hur Miner används för teknisk integration mellan datakällor och mottagande system.

Sidan fokuserar på anslutningar, jobb, dataflöden och integrationsprofiler. För en övergripande introduktion till integrationsområdet, se [[miner:integrationer|Integrationer]].

===== Vad är en systemintegration? =====

En systemintegration i Miner innebär att Miner kommunicerar med ett externt system för att läsa, skriva, hämta, bearbeta eller leverera data.

En systemintegration kan exempelvis användas för att:

  * hämta historiska mätvärden från ett system med egen datalagring
  * läsa av datapunkter kontinuerligt från ett styrsystem, en gateway eller ett protokoll
  * skicka data vidare till en databas, plattform eller extern tjänst
  * exportera data från en plattform till ett annat system
  * skriva eller överstyra värden i ett källsystem, om integrationen stödjer det
  * överföra metadata eller objektstruktur till ett mottagande system

Systemintegration är den tekniska delen av en integration. Metadata, onboarding och provisionering beskrivs på separata sidor:

  * [[miner:integrationer:metadata|Metadata]]
  * [[miner:integrationer:onboardingprocess|Onboardingprocess]]
  * [[miner:integrationer:provisionering|Provisionering]]

===== Grundprincip =====

En systemintegration består normalt av en anslutning, ett jobb och ett dataflöde.

<mermaid>
flowchart LR
    A["Anslutning<br/>till externt system"]
    B["Jobb<br/>konfiguration och urval"]
    C["Dataflöde<br/>läsning, skrivning eller leverans"]

    A --> B
    B --> C
</mermaid>

Anslutningen beskriver hur Miner kommunicerar med systemet. Jobbet beskriver vad Miner ska göra med anslutningen. Dataflödet beskriver hur information rör sig mellan källsystem, Miner och mottagande system.

===== Anslutningar =====

En anslutning beskriver hur Miner kommunicerar med ett externt system.

En anslutning kan exempelvis innehålla:

  * anslutningstyp
  * serveradress eller API-endpoint
  * autentisering
  * protokollspecifika inställningar
  * databasinställningar
  * certifikat eller nycklar
  * inställningar för läsning och skrivning

Olika anslutningstyper kräver olika uppgifter beroende på vilket system, protokoll, API eller dataformat som används.

En och samma Miner-instans kan ha flera anslutningar. En anslutning kan användas av ett eller flera jobb beroende på integrationens upplägg.

===== Jobb =====

Ett jobb definierar hur Miner ska använda en anslutning.

Jobbet anger exempelvis:

  * vilken anslutning som ska användas
  * vilka datapunkter som ska ingå
  * hur data ska hämtas
  * hur data ska bearbetas
  * vart data ska levereras
  * hur ofta data ska hämtas
  * om jobbet ska läsa, skriva, exportera eller provisionera information

I äldre dokumentation förekommer flera olika benämningar på jobbtyper, exempelvis ''Miner'', ''Poller'' och ''Exporter''. Dessa beskriver olika typer av dataflöden och används nedan för att förklara principerna.

===== Dataflöden =====

Miner kan hantera flera typer av dataflöden beroende på källsystemets egenskaper och syftet med integrationen.

^ Dataflöde ^ Beskrivning ^
| Historikhämtning | Miner hämtar data i bulk från ett system som har egen historiklagring. |
| Kontinuerlig avläsning | Miner läser av datapunkter löpande enligt ett angivet intervall. |
| Export | Miner skickar data från en plattform eller databas till ett externt system. |
| Metadataöverföring | Miner skickar metadata, objekt eller relationer till ett mottagande system. |
| Läsning och skrivning | Miner kan både läsa från och skriva till ett system, om integrationen stödjer det. |

Vilket dataflöde som används beror på källsystemets funktioner, integrationsprofilen och syftet med integrationen.

===== Historikhämtning =====

Vissa datakällor har egen historiklagring och stöd för att hämta data i bulk.

Det innebär att Miner kan ansluta till datakällan och fråga efter data som har lagrats sedan föregående hämtning. Detta är lämpligt när källsystemet själv ansvarar för kontinuerlig loggning av värden.

Exempel på system som kan ha denna typ av funktionalitet är:

  * överordnade styrsystem
  * databaser
  * mätinsamlingssystem
  * API:er med historikfunktion
  * plattformar med tidsseriedata

Historikhämtning kan vara särskilt användbart när Miner körs i en annan miljö än källsystemet, exempelvis i ett centralt nätverk eller i molnmiljö.

I äldre dokumentation används ibland benämningen ''Miner'' för jobb som hämtar data i bulk från ett system med egen historiklagring.

===== Kontinuerlig avläsning =====

Om datakällan inte har egen historiklagring, eller om den inte stödjer bulkhämtning, kan Miner läsa av datapunkter löpande.

Detta innebär att Miner själv ansvarar för att:

  * läsa av datapunkter med ett angivet intervall
  * avgöra om ett nytt värde ska sparas
  * skapa en löpande tidsserie
  * skicka vidare värden till mottagande system

Denna typ av dataflöde används ofta när Miner kommunicerar direkt med fältutrustning, styrsystem, gateways eller protokoll där historik saknas.

I äldre dokumentation används ibland benämningen ''Poller'' för jobb som kontinuerligt läser av datapunkter.

Typiska inställningar för kontinuerlig avläsning är:

^ Inställning ^ Beskrivning ^
| ''poll_interval_sec'' | Anger hur ofta Miner ska läsa från datapunkten. Anges i sekunder. |
| ''cov'' | Anger hur stor förändringen behöver vara jämfört med senast sparade värde för att ett nytt värde ska sparas. Decimaltal ska anges med punkt istället för med kommatecken.|
| ''minimal_save_interval'' | Anger största tillåtna tidsintervall mellan två sparade värden. Anges i sekunder. |

I praktiken används ofta ''cov'' tillsammans med ''minimal_save_interval''.

**Exempelscenario**: Vi vill hämta data om driftindikeringen för en pump. Driftindikeringen kan endast ha värdet "0" eller "1". Vi vill kolla efter värdet varje minut (''poll_interval_sec''="60"), men bara spara värdet om det har förändrats (''cov''="1"). Eftersom värdet kan vara oförändrat under flera veckor eller till och med månader, vill vi samtidigt spara värdet åtminstone varje timme, så att visualiseringar som ska plotta driftindikeringen alltid ska innehålla data, åtminstone varje timme (''minimal_save_intervall''="3600").

===== Läsning och skrivning =====

Vissa integrationer stödjer både läsning och skrivning.

Läsning innebär att Miner hämtar data från ett system.

Skrivning innebär att Miner skickar ett värde tillbaka till ett system, exempelvis ett börvärde, en styrsignal eller ett annat kommando.

Skrivning är endast möjligt när det underliggande systemet och integrationsprofilen stödjer detta. Skrivfunktioner bör användas kontrollerat och med hänsyn till behörighet, spårbarhet och driftsäkerhet.

I Miner används även begreppet överskrivning för vissa typer av skrivning till datapunkter.

Läs mer på sidan [[miner:admin:overskrivningar|Hantering av överskrivningar]].

===== Källsystemets betydelse =====

Hur en systemintegration konfigureras beror till stor del på vad källsystemet stödjer.

Några viktiga frågor är:

  * Har systemet egen historiklagring?
  * Finns stöd för bulk- eller batchhämtning?
  * Krävs kontinuerlig avläsning?
  * Finns metadata i källsystemet?
  * Kan datapunkter identifieras automatiskt?
  * Stödjer systemet skrivning?
  * Finns begränsningar i API, protokoll eller datamodell?
  * Krävs särskild autentisering, certifikat eller nätverksåtkomst?

Dessa egenskaper påverkar både val av integrationsprofil och hur jobbet bör konfigureras. Mera specifik information framgår från sidan [[integration:start|Dokumenterade integrationsprofiler]].


===== Integrationsprofiler =====

En integrationsprofil beskriver en färdig eller anpassad koppling mot ett visst system, protokoll, API eller dataformat.

En integrationsprofil kan exempelvis innehålla stöd för:

  * specifika API:er
  * databaskopplingar
  * fältprotokoll
  * filformat
  * meddelandeköer
  * tidsseriedatabaser
  * grafdatabaser
  * plattformsspecifika dataformat

Dokumenterade integrationsprofiler finns på sidan [[integration:start|Dokumenterade integrationsprofiler]].

===== Datapunkter =====

En datapunkt representerar normalt ett värde, en signal eller ett objekt som Miner kan läsa, skriva eller vidarebefordra information om över tiden.

Exempel på datapunkter:

  * temperaturvärde
  * börvärde
  * driftindikering
  * larmstatus
  * avläsning från energimätares räkneverk
  * flöde
  * tryck
  * styrsignal
  * beräknade värden för olika typer av variabler såsom verkningsgrad, SFP, COP med mera

Datapunkter kan ofta hämtas från källsystemet via discovery, export, API eller databasfråga. I andra fall behöver datapunkter definieras eller kompletteras manuellt.

Själva arbetet med att välja ut, klassificera och komplettera datapunkter beskrivs på sidan [[miner:integrationer:onboardingprocess|Onboardingprocess]].

===== Dataöverföring till mottagare =====

När datapunkterna har valts ut och jobbet är konfigurerat kan data levereras till ett eller flera mottagande system.

Samma dataflöde kan användas för flera mottagare beroende på integrationens upplägg.

Vilka mottagare som kan användas beror på integrationsprofil, driftmiljö och syftet med dataöverföringen.

===== Metadata i systemintegrationer =====

Metadata är inte ett krav för alla typer av dataöverföring, men metadata gör det enklare att förstå, söka, kvalitetssäkra och återanvända data.

I en systemintegration kan metadata exempelvis användas för att:

  * beskriva var datapunkten hör hemma
  * beskriva vilket system eller vilken komponent datapunkten tillhör
  * ange vilken typ av mätvärde datapunkten representerar
  * ange vilken enhet värdet har
  * ange om datapunkten är läsbar, skrivbar eller både och
  * styra hur datapunkten ska presenteras i ett mottagande system

Metadatahantering beskrivs mer detaljerat på sidan [[miner:integrationer:metadata|Metadata]].

===== Provisionering i samband med systemintegration =====

I vissa integrationer behöver metadata, objekt eller struktur skapas i ett mottagande system innan dataöverföringen startas.

Detta kallas provisionering.

Provisionering kan exempelvis vara aktuellt när:

  * metadata ska laddas upp till en grafdatabas
  * datapunkter ska skapas i ett mottagande system
  * objekt och relationer ska skapas i en plattform
  * Miner används för provisionering mot ProptechOS

Provisionering är inte nödvändig i alla systemintegrationer. Om mottagaren endast tar emot mätvärden kan dataöverföringen ofta startas utan ett separat provisioneringssteg.

Läs mer på sidan [[miner:integrationer:provisionering|Provisionering]].

===== Kvalitetssäkring =====

En systemintegration bör kvalitetssäkras innan den används i skarp drift.

Kontrollera exempelvis att:

  * anslutningen fungerar
  * rätt datapunkter har valts
  * data läses med förväntad frekvens
  * värden skickas till rätt mottagare
  * eventuella skrivfunktioner fungerar enligt avsikt
  * dataAccess och andra styrande egenskaper är korrekt inställda
  * metadata är rimlig och konsekvent
  * kvalitetsstämplar och felstatus hanteras korrekt

Läs mer på sidan [[miner:admin:qa|QA]].

===== Relaterade sidor =====

  * [[miner:integrationer|Integrationer]]
  * [[miner:integrationer:metadata|Metadata]]
  * [[miner:integrationer:onboardingprocess|Onboardingprocess]]
  * [[miner:integrationer:provisionering|Provisionering]]
  * [[miner:integrationer:drift-och-arkitektur|Drift och arkitektur]]
  * [[miner:admin:overskrivningar|Hantering av överskrivningar]]
  * [[miner:admin:qa|QA]]
  * [[integration:start|Dokumenterade integrationsprofiler]]