Deploy gir docs: d703e046f0ca05d4539d89b2b33cfa3c4a16a71f

Author: web-flow

gir/datastekker-installateur-flow.md

@@ -2,7 +2,7 @@
 
 > **⚠️ Design document — not ready for implementation**
 >
-> This document describes the intended flow for the Datastekker use case. Several open questions remain unresolved (see [Open Questions](#open-questions)). Policy field values, data-element sets, and license conditions have not been finalised. Do not use this document as the basis for implementation until it has been marked as approved.
+> This document describes the intended flow for the Datastekker use case. Several open questions remain unresolved (see [Open Questions](#open-questions)), in particular componentId-to-installationId resolution and license conditions.
 
 Datastekker (developed by 2BA) retrieves performance data from installation manufacturers and translates it into uniform performance data using the Heatpump Common Ontology. To access this data, an installer needs explicit consent from the building owner. GIR manages that authorization.
 
@@ -26,33 +26,40 @@ This guide describes how an installer requests access through a form on the Tech
 
 The flow has two phases: a one-time approval flow and a recurring operational data access pattern.
 
-```mermaid
-sequenceDiagram
-    participant Form as TechniekNederland Form
-    participant Keyper as Keyper API
-    participant Owner as Building Owner
-    participant GIR as GIR API
-    participant DS as Datastekker (2BA)
-    participant Inst as Installer
-
-    rect rgb(240, 248, 255)
-        Note over Form,GIR: Approval flow (one-time per installer / building)
-        Form->>Keyper: Create access request for vboId
-        Keyper->>Owner: Approval link by email
-        Owner->>Keyper: Authenticates and approves
-        Keyper->>GIR: Register policy (installer ↔ vboId)
-    end
-
-    rect rgb(255, 248, 240)
-        Note over Inst,GIR: Operational data access (bilateral, recurring)
-        Inst->>DS: Data request with installationId or componentId
-        opt Optional: Resolve componentId to installationId
-            Note over DS,GIR: Endpoint not yet available
-        end
-        DS->>GIR: POST /delegation — is policy valid for installer + vboId?
-        GIR-->>DS: Delegation evidence
-        DS-->>Inst: Authorised performance data
-    end
+```likec4
+// view: datastekker_overview
+specification {
+  element actor
+  element system
+}
+
+model {
+  form = system 'TechniekNederland Form'
+  keyper = system 'Keyper'
+  owner = actor 'Building Owner'
+  gir = system 'GIR'
+  ds = system 'Datastekker (2BA)'
+  inst = actor 'Installer'
+}
+
+views {
+  dynamic view datastekker_overview {
+    title 'Datastekker – Installer Access Flow'
+    variant sequence
+
+    form -> keyper 'Create access request for vboId'
+    keyper -> owner 'Approval link by email'
+    owner -> keyper 'Authenticate and approve'
+    keyper -> gir 'Register policy (installer ↔ vboId)'
+
+    inst -> ds 'Data request with componentId'
+    ds -> gir 'Resolve componentId → installationId + manufacturer info [TBD]'
+    gir -> ds 'GIRBasisdataMessage (installationId + manufacturer info)'
+    ds -> gir 'Verify delegation for installer + installationId'
+    gir -> ds 'Delegation evidence (Permit)'
+    ds -> inst 'Authorised performance data'
+  }
+}
 ```
 
 ### Steps
@@ -66,10 +73,11 @@ sequenceDiagram
 
 **Operational data access (bilateral, recurring)**
 
-5. The installer sends a data request with an installationId or componentId to Datastekker.
-6. *(Optional)* Datastekker queries GIR to resolve a componentId to an installationId.
-7. Datastekker checks the GIR delegation endpoint to verify the active policy.
-8. Datastekker returns authorised performance data to the installer.
+5. The installer sends a data request with a componentId to Datastekker.
+6. Datastekker obtains a DSGO bearer token from GIR
+7. Datastekker queries GIR to resolve the componentId to installationId and manufacturer info [TBD — see Open Questions].
+8. Datastekker checks the GIR delegation endpoint to obtain delegationEvidence
+9. Datastekker returns authorised performance data and manufacturer info to the installer.
 
 ## Before the Approval Flow
 
@@ -130,13 +138,13 @@ Content-Type: application/json
   "reference": "<UNIQUE REFERENCE>",
   "addPolicyTransactions": [
     {
-      "type": "[TBD — instance-specific]",
-      "action": "[TBD — instance-specific, e.g. read]",
-      "license": "[TBD — see open questions]",
-      "useCase": "[TBD — instance-specific]",
+      "type": "<DICO:GIR-DATASTEKKER>",
+      "action": "read",
+      "license": "[PLACEHOLDER]",
+      "useCase": "dsgo.gir-datastekker@v1",
       "issuedAt": "<UNIX TIMESTAMP>",
       "issuerId": "did:ishare:EU.NL.NTRNL-<BUILDING OWNER KVK>",
-      "attribute": "[TBD — dataset or data-element identifier (hierarchical)]",
+      "attribute": "*",
       "notBefore": "<UNIX TIMESTAMP>",
       "subjectId": "did:ishare:EU.NL.NTRNL-<INSTALLER KVK>",
       "expiration": "<UNIX TIMESTAMP matching validity period>",
@@ -145,12 +153,12 @@ Content-Type: application/json
     }
   ],
   "orchestration": {
-    "flow": "dsgo.[TBD — instance-specific]@v1"
+    "flow": "dsgo.gir-datastekker@v1"
   }
 }
 ```
 
-The fields `type`, `license`, `useCase`, `attribute`, and `orchestration.flow` are instance-specific and will be determined during technical configuration of the Datastekker integration. See the [Keyper API reference ➚](https://keyper-preview.poort8.nl/scalar/v1) for full field documentation.
+See the [Keyper API reference ➚](https://keyper-preview.poort8.nl/scalar/v1) for full field documentation.
 
 ### Step 2: Keyper Sends Approval Link to Building Owner *(Poort8)*
 
@@ -174,23 +182,44 @@ On approval, Keyper automatically registers the policy in the GIR Authorization
 
 ### Step 5: Installer Sends Data Request to Datastekker *(external)*
 
-The data exchange between the installer and Datastekker is bilateral and does not flow through GIR. The installer calls the Datastekker API directly, using an installationId or componentId as the identifier.
+The data exchange between the installer and Datastekker is bilateral and does not flow through GIR. The installer calls the Datastekker API directly, using a **componentId** (such as an SGTIN or serial number) as the identifier.
 
 > ℹ️ The Datastekker API endpoints are outside the scope of this document. Contact 2BA for the technical specifications.
 
-### Step 6 (optional): Datastekker Resolves componentId to installationId *(Poort8)*
+### Step 6: Datastekker Obtains a DSGO Bearer Token *(Poort8)*
 
-If the installer provides a `componentId` rather than an `installationId`, Datastekker needs to resolve it to an installationId before it can check the delegation policy.
+Before querying GIR, Datastekker obtains a DSGO bearer token. See [Obtaining a DSGO Bearer Token](connect-token.md) for the full procedure:
 
-> ℹ️ A GIR endpoint for resolving a componentId to an installationId is not yet available. This step is a placeholder pending that capability.
+```http
+POST https://gir-preview.poort8.nl/connect/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&scope=iSHARE&client_id=did:ishare:EU.NL.NTRNL-<2BA KVK>&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=<SIGNED_JWT>
+```
 
-### Step 7: Datastekker Checks Delegation in GIR *(Poort8)*
+### Step 7: Datastekker Resolves componentId to installationId and Retrieves Manufacturer Info *(Poort8)*
 
-Datastekker calls the GIR delegation endpoint to verify that an active and valid policy exists for the installer:
+Before checking the delegation policy, Datastekker must resolve the componentId to an installationId. This step also retrieves the `GIRBasisdataMessage`, which contains manufacturer information for the installation.
+
+> **⚠️ Open point**: GIR does not currently provide a filter parameter for componentId. The mechanism for resolving a componentId to an installationId has not yet been specified. See [Open Questions](#open-questions).
+
+Once the installationId is known, Datastekker queries GIR for the full `GIRBasisdataMessage` using the bearer token from step 6:
+
+```http
+GET https://gir-preview.poort8.nl/v1/api/GIRBasisdataMessage?installationIDValue=<INSTALLATION_ID>
+Authorization: Bearer <DSGO_ACCESS_TOKEN>
+Accept: application/json
+```
+
+The response includes `component[].productInformation.manufacturerName` and related fields, which Datastekker uses to include manufacturer details in its response to the installer.
+
+### Step 8: Datastekker Checks Delegation in GIR *(Poort8)*
+
+Using the DSGO bearer token obtained in step 6, Datastekker calls the GIR delegation endpoint to verify that an active and valid policy exists for the installer:
 
 ```http
 POST https://gir-preview.poort8.nl/delegation
-Authorization: Bearer <ACCESS_TOKEN>
+Authorization: Bearer <DSGO_ACCESS_TOKEN>
 Content-Type: application/json
 ```
 
@@ -207,11 +236,11 @@ Content-Type: application/json
           {
             "target": {
               "resource": {
-                "type": "[TBD — instance-specific]",
-                "identifiers": ["<VBOID>"],
-                "attributes": ["[TBD — dataset or data-element identifier (hierarchical)]"]
+                "type": "<DICO:GIR-DATASTEKKER>",
+                "identifiers": ["<INSTALLATION_ID>"],
+                "attributes": ["*"]
               },
-              "actions": ["[TBD — instance-specific, e.g. read]"],
+              "actions": ["read"],
               "environment": {
                 "serviceProviders": ["did:ishare:EU.NL.NTRNL-<2BA KVK>"]
               }
@@ -224,7 +253,6 @@ Content-Type: application/json
 }
 ```
 
-### Step 8: Datastekker Returns Authorised Data *(Poort8)*
 
 GIR responds with a `delegationEvidence` object. Datastekker inspects this to confirm the policy covers the requested data elements and has not expired:
 
@@ -242,18 +270,18 @@ GIR responds with a `delegationEvidence` object. Datastekker inspects this to co
         "maxDelegationDepth": 0,
         "target": {
           "environment": {
-            "licenses": ["[TBD — license identifier]"]
+            "licenses": ["[PLACEHOLDER]"]
           }
         },
         "policies": [
           {
             "target": {
               "resource": {
-                "type": "[TBD — instance-specific]",
-                "identifiers": ["<VBOID>"],
-                "attributes": ["[TBD — dataset or data-element identifier (hierarchical)]"]
+                "type": "<DICO:GIR-DATASTEKKER>",
+                "identifiers": ["<INSTALLATION_ID>"],
+                "attributes": ["*"]
               },
-              "actions": ["[TBD — instance-specific, e.g. read]"],
+              "actions": ["read"],
               "environment": {
                 "serviceProviders": ["did:ishare:EU.NL.NTRNL-<2BA KVK>"]
               }
@@ -271,6 +299,10 @@ GIR responds with a `delegationEvidence` object. Datastekker inspects this to co
 
 If no matching policy exists or the policy has expired, GIR returns a response without a `Permit` rule. Datastekker treats any non-permit result as an authorization failure and returns an error to the installer.
 
+### Step 9: Datastekker Returns Authorised Data *(2BA)*
+
+If authorization succeeds, Datastekker returns the authorised performance data together with the manufacturer information retrieved from the `GIRBasisdataMessage` in step 7.
+
 ## Policy Parameters
 
 | Parameter | Where used | Description | Status |
@@ -280,12 +312,12 @@ If no matching policy exists or the policy has expired, GIR returns a response w
 | `serviceProvider` | Keyper request, delegation request | DID of Datastekker / 2BA (the data service provider) | Required |
 | `resourceId` / `identifiers` | Keyper request, delegation request | Hierarchical resource identifier — a vboId (building) covers all its installations; an installationId scopes to a single installation. Consent may be granted at building level and enforced at installation level. | Required |
 | `notBefore` / `expiration` | Keyper request, delegation evidence | Validity period: start and end of the granted access | Required |
-| `attribute` | Keyper request, delegation request | Hierarchical data-scope identifier — a predefined dataset covers multiple data elements. Consent is granted at dataset level; enforcement can evaluate access at the level of individual data elements. | [TBD — see open questions] |
-| `type` | Keyper request, delegation request | Resource type identifier used in policy matching | [TBD — instance-specific] |
-| `action` | Keyper request, delegation request | Permitted action on the resource (e.g. `read`) | [TBD — instance-specific] |
-| `useCase` | Keyper request | Use case identifier for policy scoping | [TBD — instance-specific] |
-| `license` / `licenses` | Keyper request, delegation evidence | License identifier expressing the terms of use for the data | [TBD — see open questions] |
-| `componentId` | Datastekker internal | Component identifier provided by the installer; must be resolved to an installationId before delegation check | Endpoint not yet available |
+| `attribute` | Keyper request, delegation request | `*` (wildcard); use a predefined dataset identifier to restrict scope. See open questions #4 and #6 for the future attribute hierarchy. | `*` |
+| `type` | Keyper request, delegation request | Resource type identifier used in policy matching | `<DICO:GIR-DATASTEKKER>` |
+| `action` | Keyper request, delegation request | Permitted action on the resource | `read` |
+| `useCase` | Keyper request | Use case identifier for policy scoping | `dsgo.gir-datastekker@v1` |
+| `license` / `licenses` | Keyper request, delegation evidence | License identifier expressing the terms of use for the data | `[PLACEHOLDER]` |
+| `componentId` | Datastekker internal | Component identifier provided by the installer; must be resolved to an installationId before the GIR query and delegation check | Open point — see Open Questions |
 
 ## Open Questions
 
@@ -331,6 +363,10 @@ Open points:
 - How are the predefined sets mapped to ontology terms in the Heatpump Common Ontology / SAREF?
 - What is the governance process for adding or updating sets (versioning, backwards compatibility)?
 
+**7. ComponentId-to-installationId resolution**
+
+The installer provides a componentId (such as an SGTIN or serial number). GIR does not currently support filtering `GET /v1/api/GIRBasisdataMessage` by componentId. The mechanism for resolving a componentId to an installationId — for example via a new GIR endpoint, an external registry, or a mapping table maintained by 2BA — has not yet been specified.
+
 ---
 
 ## Further Reading