Van aanvraag tot levering

Tussen het moment dat een dataontvanger een product vindt en het moment dat er data stroomt, zitten een paar controles. Bijna alle controles doet de connector. Bij één stap beslist een mens: de rechthebbende. Deze pagina loopt de route af, en laat zien wat er gebeurt als de situatie verandert.

De route in één beeld

De dikke lijn is de weg van een aanvraag die overal door komt. Elk rood vak is een punt waar hij stopt. Stap 1 tot en met 5 gebeuren één keer per aanvraag, stap 6 bij elke nieuwe levering en stap 7 bij elk verzoek van de app. Levert de rechthebbende zelf, dan is hij ook de datahouder.

De controles van stap 2 en 3 doet de connector van de rechthebbende, stap 7 de connector van de partij die levert. Levert de rechthebbende zelf, dan is dat zijn eigen connector. Levert een datahouder namens hem, dan is het die van de datahouder (zie Leveren namens een ander). Hoe het lidmaatschap werkt, staat bij Vertrouwen en bewijs.

Het product

Een product is de data van één gebouw, die de rechthebbende in de catalogus zet. Welk deel van het gebouw, de afbakening, kiest hij bij het maken:

• een soort data, zoals Klimaat, Verlichting of Energie, of Alle data;
• de data per verdieping, als de indeling van het gebouw bekend is;
• zelf gekozen meetpunten;
• de indeling zelf: de verdiepingen en ruimtes, en welk meetpunt waar zit, zonder meetwaarden.

De rechthebbende maakt een product onder Producten, met Product aanbieden. In de kijkdemo heeft elk gebouw van RealEstator het product Alle data. Weena 505 in Rotterdam heeft ook Verlichting en Klimaat, en Delftechpark 26 in Delft heeft een product voor de indeling en een voor verdieping 2. Zie de producten van RealEstator.

Voorwaarden: wie mag aanvragen

Een product heeft een of meer voorwaarden. Een voorwaarde zegt:

Vraag	Keuzes
Wie mag aanvragen?	Alle leden van buildinglinks, of alleen een groep: klimaatoptimalisatoren, partijen voor energieflexibiliteit, facilitaire dienstverleners of partijen voor ESG-rapportage
Waarvoor?	voor elk doel, of één doel: klimaatregeling, energieflexibiliteit, facilitair beheer, ESG-rapportage of monitoring
Wat mag de dataontvanger?	Lezen, of Lezen en sturen
Tot wanneer?	een einddatum, of geen
Wie beslist over een aanvraag?	U beoordeelt elke aanvraag, of Direct toegang voor wie aan de voorwaarde voldoet

De standaard is: alle leden mogen lezen, na goedkeuring door de rechthebbende. Een aanvraag om te sturen beoordeelt de rechthebbende altijd zelf. Direct toegang is bij Lezen en sturen niet te kiezen. Wie mag sturen, beslist over installaties in een gebouw, en een lidmaatschap met een rol zegt wel wie een partij is, maar niet of de rechthebbende haar vertrouwt.

De groep komt uit de rol in het lidmaatschap van de dataontvanger (zie Rollen). Het doel geeft de dataontvanger op bij zijn aanvraag, en het komt in de overeenkomst. Of de data echt alleen voor dat doel wordt gebruikt, kan geen connector controleren. Daar houdt het rulebook van de dataspace de dataontvanger aan.

Wie niet aan de voorwaarde voldoet, ziet het product meestal niet eens in de catalogus. Het doel telt daarbij niet mee: dat geeft de dataontvanger pas op bij zijn aanvraag. Een product voor één doel ziet dus iedereen die verder aan de voorwaarde voldoet, en het aanvraagformulier toont dat doel. Een aanvraag zonder dat doel, of met een ander, wijst de connector af. En een voorwaarde die de connector niet kent, geldt als niet vervuld. Zo wordt een product nooit per ongeluk ruimer aangeboden dan bedoeld.

TechnischVoorwaarden in ODRL

Een voorwaarde is een policy in ODRL, de W3C-taal voor gebruiksrechten die het Dataspace Protocol voorschrijft. Bij Product aanbieden maakt de connector de policy voor je. De connector kent deze condities:

Conditie	Betekenis
bl:membership	De dataontvanger heeft een geldig lidmaatschap. De beheeromgeving zet het in elke voorwaarde.
bl:role	De dataontvanger heeft een van de genoemde rollen in zijn lidmaatschap, of juist geen ervan.
bl:participant	Alleen de genoemde organisaties, herkend aan hun DID. Alleen te maken op de technische pagina Voorwaarden.
odrl:dateTime	Vanaf of tot een datum, vergeleken met het moment van controleren.
odrl:purpose	Het doel dat de dataontvanger bij zijn aanvraag opgeeft.
bl:signedRequests	De dataontvanger tekent elk verzoek om data. Staat standaard in elke voorwaarde met sturen; alleen op de technische pagina Voorwaarden kun je het bewust uitzetten. De connector die levert, controleert het bij elk verzoek.

Een onbekende conditie, een onbekende operator of een datum die niet te lezen is, geldt als niet vervuld. De actie read geeft leesrecht, use, write en modify geven lees- en stuurrecht.

Technisch heeft een aanbod twee policies: een voor wie het aanbod in de catalogus ziet, en een voor wie er een overeenkomst op krijgt. Product aanbieden gebruikt voor beide dezelfde voorwaarde. Op de technische pagina Catalogus kan een rechthebbende een aanbod ook zichtbaar maken voor alle leden, zodat wie niet aan de voorwaarde voldoet het wel ziet, maar bij een aanvraag wordt afgewezen.

Aanvragen

De dataontvanger zoekt onder Data zoeken op adres, plaats of partij, kiest een product en een voorwaarde, en geeft het doel op. Biedt de rechthebbende ook de indeling van het gebouw aan, dan kan de dataontvanger die in dezelfde handeling aanvragen. De rechthebbende ziet dat als één aanvraag met twee onderdelen.

De connector van de rechthebbende controleert de aanvraag meteen: is de dataontvanger actief lid, en voldoet hij aan de voorwaarde? Zo niet, dan beëindigt de connector de aanvraag direct, zonder dat er een mens aan te pas komt. De dataontvanger ziet dan de reden.

Voldoet hij wel, dan krijgt hij direct toegang, of wacht de aanvraag op de rechthebbende. Dat laatste gebeurt ook als de voorwaarde op direct toegang staat, maar:

• de aanvraag sturen vraagt;
• de rechthebbende de toegang van deze dataontvanger tot dit product eerder heeft ingetrokken.

De rechthebbende beslist

De rechthebbende ziet wachtende aanvragen onder Aanvragen. Bij een aanvraag staat wie er vraagt, welk product, welke voorwaarde en welk doel. Hij kiest:

• Goedkeuren. Er ontstaat een ondertekende overeenkomst.
• Goedkeuren voor alleen lezen, bij een aanvraag om te sturen. De dataontvanger krijgt dan minder dan hij vroeg, nooit meer.
• Afwijzen, eventueel met een reden die de dataontvanger ziet.
• Later beslissen.

Goedkeuren of afwijzen kan een gebruiker met de rol operator of beheerder. Een viewer kijkt alleen. Bij het goedkeuren kijkt de connector nog één keer in het register van de Trust Authority of de dataontvanger actief lid is.

Per gebouw kan in deze versie maar één dataontvanger tegelijk sturen. Stuurt er al een, dan staat dat bij de aanvraag, en kan de rechthebbende alleen goedkeuren voor lezen.

Beslist niemand, dan verloopt de aanvraag na een termijn, standaard zeven dagen. Beide connectors controleren dat elke minuut, ook als de andere onbereikbaar is. De dataontvanger kan daarna opnieuw aanvragen. Zolang de aanvraag wacht, ziet hij haar onder Aanvragen, op het tabblad Verstuurd.

De overeenkomst

De overeenkomst legt vast wat er is afgesproken:

• welk product, en precies welke gebouwen en meetpunten daarbij hoorden op het moment van sluiten;
• of de dataontvanger alleen mag lezen of ook mag sturen;
• het doel en de einddatum, als de voorwaarde die noemt;
• of elk verzoek om data ondertekend moet zijn. Bij sturen is dat standaard zo.

Afspraak is afspraak. Verandert de rechthebbende later het product of de voorwaarde, dan geldt dat voor nieuwe aanvragen. Een gesloten overeenkomst blijft zoals ze is. Wie meer wil, vraagt opnieuw aan.

TechnischAanvragen en beslissen in het protocol

• De aanvraag en de overeenkomst lopen via het Dataspace Protocol (DSP). Een onderhandeling begint altijd bij de dataontvanger, vanuit de catalogus.
• Zolang de rechthebbende niet heeft beslist, blijft de onderhandeling in de DSP-status REQUESTED. De connector meldt de wachtende beoordeling en de uiterste datum als extensie in zijn antwoord. Een connector van een andere leverancier negeert die en ziet een lange REQUESTED.
• Afwijzen en verlopen eindigen met een ContractNegotiationTerminationMessage.
• In de beheer-API gaat het met POST /api/v1/negotiations/{id}/approve en …/reject. Goedkeuren kan daar ook een deel van de meetpunten geven. De termijn staat in BL_APPROVAL_TTL_SECS.
• Wat er in de overeenkomst staat, is het target in ODRL: een AssetCollection met de gebouwen (bl:object) en de meetpunten (bl:point).

Na de overeenkomst: de levering

Een overeenkomst levert nog geen data. Direct na de overeenkomst vraagt de connector van de dataontvanger zelf de levering aan. De connector van de rechthebbende controleert dan of de overeenkomst nog loopt en toetst de voorwaarde opnieuw, met het lidmaatschap dat de dataontvanger nu laat zien en de datum van vandaag. Klopt alles, dan start hij de levering en krijgt de dataontvanger een adres en een toegangstoken. Dat token is een uur geldig, en de gateway van de dataontvanger vernieuwt het zelf.

Bij de dataontvanger is er nu een abonnement. Onder Apps geeft hij het aan een of meer van zijn apps, met alleen lezen of lezen en sturen. Een app kan nooit meer dan de overeenkomst toestaat.

De app haalt de data op via de gateway van de eigen connector, met de sleutel van de app. De gateway controleert eerst of de app dit abonnement mag gebruiken, en of hij mag sturen. Daarna gaat het verzoek naar de connector die levert.

Bij elk verzoek

Vanaf dat moment beslist de connector die levert over elk verzoek. Hij laat een verzoek alleen door naar het systeem als alles hieronder klopt:

• het toegangstoken is geldig en hoort bij een levering die loopt. Een gepauzeerde of beëindigde levering geeft niets meer;
• de overeenkomst staat de handeling toe. Opvragen is lezen, al het andere is sturen. Wie alleen mag lezen, krijgt op een stuuropdracht een weigering;
• het gebouw in het verzoek valt binnen de overeenkomst, en de gevraagde meetpunten ook. Mag de dataontvanger een deel van het gebouw, dan moet hij de meetpunten noemen die hij wil;
• het verzoek is ondertekend door de dataontvanger, als de overeenkomst dat vraagt. De handtekening is hooguit een minuut oud en telt maar één keer;
• levert een datahouder namens de rechthebbende, dan is die aanwijzing nog actief.

Valt een verzoek erbuiten, dan weigert de connector het. Hij filtert niet stil en vult niets aan. Het systeem krijgt alleen verzoeken die al zijn goedgekeurd, en de connector ondertekent elk antwoord.

Daarnaast toetst de connector van de rechthebbende elke minuut alle lopende leveringen opnieuw. Is de dataontvanger nog actief lid, en klopt de voorwaarde nog, met de rollen uit het register van de Trust Authority en de datum van vandaag? Zo niet, dan beëindigt hij de levering, met de reden erbij. Een verstreken einddatum of een ingetrokken rol stopt een levering dus binnen een minuut.

TechnischWeigeringen van de connector die levert

• 401 bij een ontbrekend of verlopen toegangstoken, een ontbrekende handtekening terwijl de overeenkomst bl:signedRequests vraagt, of een handtekening die ongeldig, te oud of al gebruikt is.
• 403 bij een onbekende of vervangen levering, een levering die niet loopt, een handeling die de overeenkomst niet toestaat, een gebouw of meetpunt buiten de afbakening, een handtekening van een ander dan de dataontvanger, of een aanwijzing die niet meer actief is.
• Bij een afbakening kleiner dan het gebouw moet een leesverzoek point_ids meesturen, en weigert de connector include=. Een stuuropdracht wordt per point_id gecontroleerd.
• De body is altijd {"error": {"code": …, "message": …, "retryable": …}}.
• Bij het vernieuwen van het token controleert de connector of het token bij de levering hoort, of die nog loopt en of een eventuele aanwijzing actief is. Lidmaatschap, rol en datum toetst de controle van elke minuut.

Als de situatie verandert

Niet elke verandering stopt een levering die al loopt.

Wat verandert	Wat meteen stopt	Wat later telt
De rechthebbende trekt de toegang in	De levering, direct. De overeenkomst geeft geen toegang meer.	Vraagt de dataontvanger opnieuw aan, dan beoordeelt de rechthebbende dat altijd zelf.
De dataontvanger zegt het abonnement op	De levering. De overeenkomst eindigt.	Een nieuwe aanvraag wordt gewoon behandeld.
De levering wordt gepauzeerd	Elk verzoek, tot de levering wordt hervat.	De overeenkomst blijft bestaan.
De einddatum van de voorwaarde is voorbij	Lopende leveringen, binnen een minuut.	Geen nieuwe levering op die overeenkomst.
Een rol staat niet meer in het lidmaatschap	Lopende leveringen waarvan de voorwaarde die rol vraagt, binnen een minuut.	Nieuwe aanvragen en leveringen worden getoetst aan de nieuwe rollen.
De Trust Authority schorst de dataontvanger	Lopende leveringen, binnen een minuut.	Elke nieuwe vraag mislukt, omdat het lidmaatschap is ingetrokken.
De rechthebbende wijzigt het product of de voorwaarde	Niets.	Nieuwe aanvragen.

Intrekken doet de rechthebbende onder Wie gebruikt uw data, met Toegang intrekken in het menu van een rij. Een reden is optioneel en gaat mee naar de dataontvanger. Intrekken is blijvend. De overeenkomst blijft bewaard als bewijs. Op dat scherm ziet de rechthebbende per dataontvanger ook apart de toegang die hij gaf, en het gebruik: Haalt data op, Gepauzeerd of Gebruikt het niet.

Opzeggen doet de dataontvanger zelf, met Abonnement opzeggen onder Protocol en bewijs, Verbindingen. De connector stuurt dan een eigen, ondertekend bericht aan de rechthebbende, want het Dataspace Protocol kent geen bericht om een overeenkomst te beëindigen. Een rechthebbende met een connector van een andere leverancier kent dat bericht niet. Daar loopt de overeenkomst door tot de einddatum.

Pauzeren, hervatten en beëindigen van een levering kan aan beide kanten, onder Protocol en bewijs, Leveringen.

In de kijkdemo

• Bij RealEstator zie je onder Wie gebruikt uw data welke dataontvangers toegang hebben, wat ze mogen en of ze de data ophalen. Optimaforma stuurt onder meer in Weena 505 en Delftechpark 26, Facilitair Inzicht leest.
• Bij de producten van RealEstator zie je per product de voorwaarden: alle leden mogen lezen, met direct toegang, en lezen en sturen mogen alleen klimaatoptimalisatoren of partijen voor energieflexibiliteit, na beoordeling door RealEstator. Klimaat · Weena 505 mogen alle leden lezen, maar alleen voor klimaatregeling.
• Bij de apps van Optimaforma zie je welke abonnementen een app gebruikt.

De kijkdemo is alleen om te kijken. Wil je zelf een aanvraag doen, goedkeuren of intrekken, start dan de simulatie op je eigen computer. Vraag daar bijvoorbeeld als Facilitair Inzicht het product voor klimaatoptimalisatoren aan: de connector van RealEstator vindt de rol niet en beëindigt de aanvraag meteen, met de voorwaarden erbij.