miner:integrationer:metadata [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.
====== Metadata ======

Den här sidan beskriver hur metadata används i Miner för att beskriva, strukturera och kvalitetssäkra datapunkter.

Med metadata menas information som beskriver en datapunkt och dess sammanhang och ger den kontext. Metadata gör det möjligt att förstå vad en datapunkt representerar, var den hör hemma, hur den ska användas och hur den relaterar till andra objekt.

Miner ger användaren möjlighet att ange valfri uppsättning av metadata, för valfri utgående anslutning från ett dataöverföringsjobb. Dessa metadata kallas för ''attribut'' i Miner.

För en övergripande beskrivning av integrationsområdet, se [[miner:integrationer|Integrationer]].

===== Syfte =====

Syftet med metadata i Miner är att göra data mer användbar.

Utan metadata är en datapunkt ofta bara ett tekniskt namn, en adress, ett ID eller en signal från ett källsystem. Med metadata kan datapunkten beskrivas på ett sätt som gör den begriplig för mottagande system, användare, analysverktyg och framtida integrationsflöden.

Metadata används bland annat för att:

  * beskriva vad en datapunkt representerar
  * koppla datapunkter till byggnader, system, komponenter och funktioner
  * ange mätstorhet, enhet och datatyp
  * beskriva om datapunkten kan läsas eller skrivas
  * skapa konsekventa namn och visningsnamn
  * möjliggöra sökning, filtrering och aggregering
  * förbereda provisionering till mottagande system
  * skapa spårbarhet och dokumentation kring integrationer

===== Metadata i integrationsflödet =====

Metadata är en del av integrationsarbetet, men är inte samma sak som själva dataöverföringen.

^ Del ^ Beskrivning ^
| Systemintegration | Miner ansluter till källsystem och mottagare samt hanterar teknisk dataöverföring. |
| Datapunkter | Signaler, mätvärden eller objekt som hämtas från källsystemet. |
| Metadata | Information som beskriver datapunkterna och deras sammanhang. |
| Onboarding | Arbetsprocessen där datapunkter väljs ut, kompletteras med metadata och kvalitetssäkras. |
| Provisionering | Skapande eller uppdatering av metadata, objekt eller relationer i ett mottagande system. Ett steg som ibland kan behöva genomföras innan själva överföringen av mätvärden initieras. |

Läs mer om den praktiska arbetsprocessen på sidan [[miner:integrationer:onboardingprocess|Onboardingprocess]].

===== Grundattribut och metadataattribut =====

I Miner finns både grundattribut och metadataattribut.

**Grundattribut** är attribut som Miner använder för att datapunkten ska fungera tekniskt i ett jobb. Dessa ska normalt inte tas bort eller byta namn vid export, redigering eller import av CSV-filer.

**Metadataattribut** är kompletterande attribut som beskriver datapunktens sammanhang, exempelvis byggnad, system, komponent, funktion, enhet, placering eller visningsnamn.

===== Grundattribut som inte bör tas bort =====

Följande attribut är exempel på grundattribut som normalt inte ska tas bort från en datapunkt eller från ett exporterat/importerat CSV-underlag.

^ Attribut ^ Beskrivning ^ Kommentar ^
| ''UUID'' | Unik identifierare för datapunkten i Miner-jobbet. | Ska normalt inte ändras manuellt. Används för att Miner ska kunna känna igen datapunkten vid uppdateringar. |
| ''source_label'' | Datapunktens beteckning eller identifierare i källsystemet. | Viktig för spårbarhet mot källsystemet. Bör inte kunna ändras. |
| ''label'' | Beteckning som används vid leverans eller presentation mot mottagarsystemet. | Kan ofta vara samma som ''source_label'', men kan anpassas vid behov för varje output_connection. Om kunden har en specifik standard för märkning av datapunkter som skiljer sig från hur datapunkterna är märkta i källsystemet, går det att justera detta genom att ändra ''label'', eller lägga till ett anpassat attribut med önskad sammansättning.|
| ''poll_interval_sec'' | Anger hur ofta Miner ska läsa datapunkten från källsystemet. | Anges i sekunder, exempelvis 300 för 5-minutersavläsningar. Relevant för jobb där Miner pollar datapunkter. |
| ''cov'' | Change of Value. Anger hur stor förändringen måste vara för att ett nytt värde ska sparas. | Vid CSV-import ska punkt användas som decimaltecken, exempelvis ''0.5''. |
| ''minimal_save_interval'' | Anger största tillåtna tid mellan två sparade värden. | Rekommenderas tillsammans med ''cov'' för att undvika långa luckor i tidsserier. Värdet anges i hela sekunder, exempelvis 3600 för en timme. |
| ''data_access'' | Anger om datapunkten kan läsas eller både läsas och skrivas. | Vanliga värden är ''r'' och ''rw''. Bör kontrolleras särskilt vid onboarding. |
| ''config_status'' | Anger om datapunkten är färdigkonfigurerad. | ''Done'' används för datapunkter som är klara att användas i dataöverföringen. |

Vilka grundattribut som finns kan variera mellan olika integrationsprofiler, jobbtyper och Miner-versioner. Utgå därför alltid från det CSV-underlag som exporteras från det aktuella jobbet.

===== Vad kan metadata beskriva? =====

Metadata kan beskriva flera olika aspekter av en datapunkt.

^ Område ^ Exempel på metadata ^
| Ursprung | Källsystem, anslutning, ursprungligt ID, ursprungligt namn |
| Struktur | Byggnad, anläggning, system, komponent, utrustning |
| Funktion | Vad datapunkten representerar, exempelvis mätvärde, börvärde, driftindikering eller larm |
| Mätinformation | Mätstorhet, enhet, datatyp, skalning |
| Placering | Rum, zon, våningsplan, byggnad eller annan fysisk/logisk placering |
| Åtkomst | Om datapunkten kan läsas, skrivas eller både läsas och skrivas |
| Presentation | Visningsnamn, teknisk beteckning, populärnamn eller annan benämning |
| Relationer | Relation till system, komponenter, rum, byggnader eller andra objekt |
| Förvaltning | Status, kommentarer, kvalitetssäkring, konfigurationsstatus |

Vilka metadatafält som används beror på integrationsprofil, mottagande system, valt metadataupplägg och projektets krav.

===== Metadata är inte låst till en viss standard =====

Miner är inte beroende av någon specifik informationsmodell eller metadatastandard.

Det innebär att metadata kan utgå från:

  * egna metadatafält
  * kundspecifika metadataupplägg
  * projektspecifika mallar
  * standardiserade metadatauppsättningar
  * metadatalistor från anslutna system
  * manuella klassificeringssystem
  * kombinationer av flera olika källor

Exempel på standardiserade eller återanvändbara metadataupplägg kan vara klasslistor, komponentlistor, klasslistor ur ontologier, systembeteckningar, namngivningsregler eller scheman som används för en viss mottagande plattform.

Vissa anslutningar kan också tillhandahålla metadatalistor eller mallar som stöd i onboardingarbetet. Det kan exempelvis handla om listor över byggnader, rum, komponenter, klasser eller andra objekt som datapunkter kan kopplas till.

===== Attribut och fältnamn =====

I Miner kan metadata beskrivas som attribut på datapunkter.

Ett attribut består normalt av:

  * ett fältnamn
  * ett värde
  * eventuellt ett prefix eller en struktur som anger hur attributet ska tolkas

Exempel för att illustrera principen:

^ Attribut ^ Exempelvärde ^ Typ av attribut ^ Beskrivning ^
| ''source_label'' | ''VS01-EM01-PV'' | Grundattribut | Ursprunglig beteckning eller etikett från källsystemet. |
| ''label'' | ''2455_A-VS01-EM01-E'' | Grundattribut | Kundspecifik standard, där beteckningen ska anges enligt standarden: fastighetsbeteckning_byggnadsbetecking-systembeteckning-komponentbeteckning-komponentkvalificerare. Komponentkvalificerarna ska vidare baseras på en standardiserad lista, där "E" representerar "Energianvändning". |
| ''data_access'' | ''r'' | Grundattribut | Anger om datapunkten kan läsas eller skrivas. |
| ''config_status'' | ''Done'' | Grundattribut | Anger att datapunkten är färdigkonfigurerad. |
| ''!building'' | ''Hus A'' | Konstant | Anger byggnad eller anläggning. |
| ''!system'' | ''VS01'' | Konstant | Anger tekniskt system. |
| ''!equipment'' | ''EM01'' | Konstant | Anger utrustning eller komponent. |
| ''!qualifier'' | ''E'' | Konstant | Anger datapunktens funktion eller kvalificerare. |
| ''!unit'' | ''kWh'' | Konstant | Anger enhet. |
| ''!brick:PointClass'' | ''Energy_Usage_Sensor'' | Konstant | Anger klassificering av datapunkten enligt Brick Schema. |
| ''!brick:SystemClass'' | ''Radiation_Hot_Water_System'' | Konstant | Anger klassificering av systemet enligt Brick Schema. |
| ''!brick:EquipmentClass'' | ''Hot_Water_Meter'' | Konstant | Anger klassificering av komponenten enligt Brick Schema. |
| ''!description'' | ''Energimätning VS01'' | Konstant | Namn som kan visas i mottagande system. |
| ''@qa_status'' | ''0'' | Dynamisk | Anpassad flagga för att ange om värdet för mätarens räkneverk har kontrollerats mot den fysiska mätaren eller ej. |

Fältnamn och värden kan anpassas efter projektets behov. I vissa integrationer används särskilda prefix eller scheman för att skilja mellan olika typer av attribut.

===== Prefix för attribut =====

Vid export, import och arbete med metadata kan prefix användas för att ange hur ett attribut ska tolkas.

Prefixet anges först i attributnamnet.

^ Prefix ^ Typ ^ Betydelse ^ Typisk användning ^
| ''#'' | Kommentar eller arbetsattribut | Intern information som används under onboarding eller kvalitetssäkring. | Onboardingflaggor, noteringar, arbetsfält, temporär klassificering. |
| ''@'' | Dynamiskt attribut | Attribut vars värde kan ändras över tid och hanteras som dynamisk information. | Status, driftläge eller annan metadata som kan förändras. |
| ''!'' | Konstant attribut | Attribut som ska behandlas som fast metadata. | Byggnad, system, komponent, enhet eller annan metadata som ska gälla som konstant information. |
| inget prefix | Grundattribut | Attribut som hanteras direkt av Miner eller av aktuell integration. | ''source_label'', ''cov'', ''config_status'', ''data_access'' med flera. |

Exakt hur prefixen används kan bero på integration och mottagande system. Kontrollera därför alltid aktuellt arbetsflöde och integrationsprofil.

===== Prefixet # =====

Prefixet ''#'' används för kommentarer, arbetsfält och intern information under onboarding.

Attribut med ''#'' kan användas för att stödja arbetsprocessen utan att nödvändigtvis skickas vidare som metadata till mottagande system.

Exempel:

^ Attribut ^ Exempelvärde ^ Användning ^
| ''#onboarding'' | ''1'' | Datapunkten ska onboardas. |
| ''#onboarding'' | ''0'' | Datapunkten ska inte onboardas. |
| ''#onboarding'' | ''9'' | Datapunkten behöver kontrolleras eller diskuteras vidare. |
| ''#comment'' | ''Kontrollera placering'' | Intern notering. |
| ''#building'' | ''Hus A'' | Arbetsfält för byggnad. Värdet ska inte sparas med avläsningen. |
| ''#system'' | ''LB01'' | Arbetsfält för systembeteckning. Värdet ska inte sparas med avläsningen. |
| ''#equipment'' | ''GT11'' | Arbetsfält för komponentbeteckning. Värdet ska inte sparas med avläsningen.  |
| ''#qualifier'' | ''PV'' | Arbetsfält för datapunktens funktion eller kvalificerare. Värdet ska inte sparas med avläsningen. |

Prefixet ''#'' är särskilt användbart i kalkylblad och CSV-underlag där man vill ha med arbetskolumner som stöd för klassificering, formler eller QA utan att dessa nödvändigtvis ska bli metadata i mottagande system.

**Observera** att attribut med prefixet ''#'' kommer att överföras till grafdatabaser som del av Miners graf, om det aktuella jobbet är del av ett dataöverföringsjobb till en grafdatabas. I grafdatabasen kommer det däremot att anges att attributet är att anse som just en kommentar.

===== Prefixet @ =====

Prefixet ''@'' används för dynamiska attribut.

Dynamiska attribut används när informationen kan förändras över tid och inte bör behandlas som fast metadata.

Exempel:

^ Attribut ^ Exempelvärde ^ Användning ^
| ''@status'' | ''Aktiv'' | Statusinformation som kan förändras. |
| ''@mode'' | ''Auto'' | Driftläge eller annan dynamisk metadata. |
| ''@state'' | ''Normal'' | Tillstånd som kan förändras över tid. |

Dynamiska attribut bör användas när värdet inte ska betraktas som en fast egenskap hos datapunkten.

===== Prefixet ! =====

Prefixet ''!'' används för konstanta attribut.

Konstanta attribut beskriver information som ska behandlas som fast metadata för datapunkten.

Exempel:

^ Attribut ^ Exempelvärde ^ Användning ^
| ''!building'' | ''Hus A'' | Fast metadata som beskriver byggnad. |
| ''!system'' | ''LB01'' | Fast metadata som beskriver systemtillhörighet. |
| ''!equipment'' | ''GT11'' | Fast metadata som beskriver komponent. |
| ''!unit'' | ''°C'' | Fast metadata som beskriver enhet. |

Använd ''!'' med försiktighet. Konstant metadata kan påverka hur datapunkten tolkas i mottagande system och kan i vissa flöden även påverka historiska värden eller historisk metadata.

===== Grundattribut utan prefix =====

Attribut utan prefix kan vara grundattribut eller vanliga metadatafält.

Exempel på grundattribut utan prefix:

  * ''UUID''
  * ''source_label''
  * ''label''
  * ''poll_interval_sec''
  * ''cov''
  * ''minimal_save_interval''
  * ''data_access''
  * ''config_status''

Dessa attribut används av Miner eller av aktuell integrationsprofil och bör normalt inte tas bort.

Exempel på vanliga metadatafält utan prefix:

  * ''building''
  * ''system''
  * ''equipment''
  * ''unit''
  * ''display_name''

Hur attribut utan prefix ska tolkas beror på fältnamn, integration och mottagande system.

===== Obligatorisk och frivillig metadata =====

Vilken metadata som är obligatorisk beror på användningsfallet.

En enkel dataöverföring till en tidsseriedatabas kan fungera med relativt lite metadata, medan provisionering till en mottagande plattform eller grafdatabas kan kräva strukturerad information.

Exempel på metadata som ofta är viktig:

  * unik identifierare för datapunkten
  * ursprunglig beteckning eller etikett
  * byggnad eller anläggning
  * systemtillhörighet
  * komponent eller utrustning
  * funktion eller datapunktstyp
  * mätstorhet
  * enhet
  * läs-/skrivbarhet
  * visningsnamn
  * konfigurationsstatus

Exempel på metadata som kan vara frivillig eller projektspecifik:

  * rum eller zon
  * våningsplan
  * relationer till andra objekt
  * klassificering enligt specifikt schema
  * kommentarer
  * kvalitetssäkringsstatus
  * systemspecifika attribut
  * kundspecifika attribut

===== Identifierare och nycklar =====

För att datapunkter ska kunna hanteras stabilt över tid behöver de kunna identifieras på ett entydigt sätt.

Identifieraren kan komma från källsystemet, men den kan också behöva byggas upp av flera attribut.

Exempel på attribut som kan ingå i en sammansatt nyckel:

  * byggnad
  * system
  * komponent
  * datapunktens funktion
  * ursprungligt ID
  * källsystem
  * anslutning

Exempel:

^ Byggnad ^ System ^ Komponent ^ Funktion ^ Möjlig sammansatt identifierare ^
| ''Hus A'' | ''LB01'' | ''GT11'' | ''PV'' | ''HusA-LB01-GT11-PV'' |

En tydlig identifieringsprincip gör det lättare att uppdatera metadata, hantera ändringar och undvika dubbletter.

===== Namn, beteckningar och visningsnamn =====

I många källsystem är datapunkter namngivna med tekniska beteckningar.

Dessa beteckningar är viktiga för spårbarhet, men är inte alltid lämpliga som visningsnamn i mottagande system.

Det kan därför vara lämpligt att skilja mellan:

^ Typ av namn ^ Syfte ^ Exempel ^
| Ursprunglig beteckning | Bevarar kopplingen till källsystemet. | ''LB01-GT11-PV'' |
| Systembeteckning | Anger vilket system datapunkten hör till. | ''LB01'' |
| Komponentbeteckning | Anger vilken komponent datapunkten hör till. | ''GT11'' |
| Funktion | Anger datapunktens roll. | ''Mätvärde'' |
| Visningsnamn | Användarvänligt namn i mottagande system. | ''Tilluftstemperatur LB01'' |

En bra princip är att bevara teknisk metadata för spårbarhet och samtidigt komplettera med läsbara namn för användning i gränssnitt, rapporter och analyser.

===== data_access =====

Attributet ''data_access'' används för att beskriva om en datapunkt kan läsas eller skrivas.

^ Värde ^ Betydelse ^
| ''r'' | Datapunkten kan läsas. |
| ''rw'' | Datapunkten kan både läsas och skrivas. |

Det är viktigt att kontrollera ''data_access'' i samband med onboarding och kvalitetssäkring.

Vissa källsystem eller API:er kan tekniskt tillåta skrivning till många datapunkter, utan att alla dessa datapunkter bör betraktas som styrbara i mottagande system.

Felaktig klassificering av läs-/skrivbarhet kan påverka:

  * hur datapunkten visas
  * om datapunkten provisioneras som styrbar
  * vilka funktioner som blir tillgängliga i mottagande system
  * säkerhet och driftansvar

Läs mer om läsning och skrivning på sidan [[miner:integrationer:systemintegration|Systemintegration]].

===== config_status =====

Attributet ''config_status'' kan användas för att ange om en datapunkt är färdigkonfigurerad.

Ett vanligt värde är:

^ Värde ^ Betydelse ^
| ''Done'' | Datapunkten är färdigkonfigurerad och kan användas i dataöverföringen. |

Miner sparar normalt endast avläsningar från datapunkter som är klarmarkerade i jobbet. Klarmarkering kan göras via Miners webbgränssnitt eller genom att ange ''config_status=Done'' i integrationsunderlaget vid CSV-import.

Sätt inte ''config_status=Done'' förrän datapunktens urval, metadata och eventuella kvalitetssäkring är klara.

===== cov och minimal_save_interval =====

Attributet ''cov'' står för Change of Value och anger hur stor förändringen behöver vara för att ett nytt värde ska sparas.

Attributet ''minimal_save_interval'' anger största tillåtna tidsintervall mellan två sparade värden.

Dessa attribut är tekniska grundattribut, men de är viktiga i metadata- och onboardingarbetet eftersom de påverkar hur tidsserier byggs upp och hur datakvalitet uppfattas i mottagande system.

Exempel:

^ poll_interval_sec ^ cov ^ minimal_save_interval ^ Betydelse ^
| ''60'' | ''0.5'' | ''3600'' | Läs värdet varje minut. Spara nytt värde om förändringen är minst 0,5. Spara minst ett värde per timme. |

Vid CSV-import ska punkt användas som decimaltecken i ''cov'', exempelvis ''0.5''.

===== Metadata från anslutna system =====

Vissa anslutningar kan tillhandahålla metadata som stöd för onboarding.

Det kan exempelvis vara:

  * listor över byggnader
  * listor över rum eller zoner
  * klasslistor
  * komponentlistor
  * systembeteckningar
  * tillåtna värden för vissa metadatafält
  * objekt eller relationer från en mottagande plattform

Dessa listor kan användas för att standardisera metadatasättningen och minska risken för stavfel, dubbletter eller inkonsekventa benämningar.

Exempel:

  * en anslutning mot en mottagande plattform kan tillhandahålla listor över byggnader och rum
  * en anslutning mot en grafdatabas kan tillhandahålla befintliga objekt och relationer
  * en kundspecifik anslutning kan tillhandahålla standardiserade benämningar för system och komponenter

===== Metadata och standardisering =====

Metadata kan användas för att skapa en gemensam struktur över flera system, byggnader och projekt.

Standardisering kan omfatta:

  * gemensamma fältnamn
  * gemensamma klasslistor
  * gemensamma beteckningsprinciper
  * gemensamma enheter
  * gemensamma visningsnamn
  * regler för hur system och komponenter identifieras
  * regler för vilka datapunkter som får vara skrivbara

Standardisering gör det lättare att:

  * återanvända integrationer
  * söka och filtrera datapunkter
  * jämföra data mellan byggnader
  * bygga generella dashboards
  * använda data för analys och optimering
  * förvalta integrationer över tid

===== Metadata och provisionering =====

I vissa integrationer används metadata för att skapa eller uppdatera information i ett mottagande system.

Detta kallas provisionering.

Provisionering kan exempelvis innebära att Miner:

  * laddar upp metadata till en grafdatabas
  * skapar datapunkter i en mottagande plattform
  * uppdaterar objekt
  * skapar relationer mellan objekt
  * förbereder mottagaren innan dataöverföringen startas

Provisionering är inte nödvändig i alla integrationer. 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]].

===== Metadata och kunskapsmodell =====

Miner kan använda metadata för att beskriva integrationer på ett mer strukturerat sätt än enbart som tabeller eller konfigurationsfiler.

Anslutningar, datapunkter, metadata och relationer kan beskrivas som delar av en gemensam kunskapsmodell.

Det gör det möjligt att:

  * dokumentera integrationer
  * förstå relationer mellan datapunkter och objekt
  * exportera metadata till andra system
  * använda grafdatabaser eller triplestores
  * skapa sökbara och maskinläsbara beskrivningar av integrationer
  * bygga underlag för framtida analys- och AI-tillämpningar

Hur kunskapsmodellen används beror på integrationens syfte och mottagande system.

===== Metadata och kvalitetssäkring =====

Metadata bör kvalitetssäkras innan dataöverföringen startas.

Kontrollera exempelvis att:

  * obligatoriska metadatafält är ifyllda
  * grundattribut inte har tagits bort eller ändrats felaktigt
  * identifierare är unika och stabila
  * enheter och mätstorheter är rimliga
  * system- och komponentbeteckningar är konsekventa
  * visningsnamn är begripliga
  * ''data_access'' är korrekt
  * ''config_status'' endast används för färdigkonfigurerade datapunkter
  * eventuella relationer till byggnad, system, komponent eller placering är korrekta
  * avvikelser är dokumenterade

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

===== Rekommenderat arbetssätt =====

Ett rekommenderat arbetssätt är att hantera metadata stegvis.

  - Börja med metadata som kommer från källsystemet.
  - Identifiera vilka datapunkter som ska ingå.
  - Säkerställ att grundattributen finns kvar och har rimliga värden.
  - Bestäm vilka metadatafält som krävs för mottagande system.
  - Komplettera datapunkterna med system, komponent, funktion, enhet och visningsnamn.
  - Kontrollera läs-/skrivbarhet.
  - Kvalitetssäkra metadata.
  - Sätt ''config_status=Done'' när datapunkten är färdig.
  - Provisionera metadata eller objekt om det behövs.
  - Starta dataöverföringen.

Den praktiska processen beskrivs mer utförligt på sidan [[miner:integrationer:onboardingprocess|Onboardingprocess]].

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

  * [[miner:integrationer|Integrationer]]
  * [[miner:integrationer:systemintegration|Systemintegration]]
  * [[miner:integrationer:onboardingprocess|Onboardingprocess]]
  * [[miner:integrationer:provisionering|Provisionering]]
  * [[miner:admin:qa|QA]]
  * [[miner:anvandning:kommaigang|Komma igång]]
  * [[integration:start|Dokumenterade integrationsprofiler]]