From 5e04b245086098ebaa79aff3fee93330e1514045 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 25 Mar 2026 11:00:51 +0100 Subject: [PATCH 01/10] Create first part of tutorial for the interaction of metabase and database --- README.md | 5 +++++ .../interaction_metabase_database.md | 20 +++++++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 docs/tutorials/interaction_metabase_database.md diff --git a/README.md b/README.md index d4ca61833..f04f033fc 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,11 @@ In another shell 1. List all backend GNU Make targets by running `make help`. 1. For example, update packages and tools by running `make update`. 1. Drop out of the container by running `exit` or pressing `Ctrl-D`. +1. If you want to test the interaction between the metabase and a product data + server, follow the README section [Development/Getting Started]() of + repository [database](https://github.com/building-envelope-data/database). + Then you can test the interaction of metabase and a product data server + following the [tutorial](https://github.com/building-envelope-data/metabase/docs/tutorials/interaction_metabase_database.md). ### Migrating the Database diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md new file mode 100644 index 000000000..66e1b2ee4 --- /dev/null +++ b/docs/tutorials/interaction_metabase_database.md @@ -0,0 +1,20 @@ +# Test the interaction of metabase and database + +1. Follow the sections `Getting Started` of [metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) + and [database](https://github.com/building-envelope-data/database?tab=readme-ov-file#getting-started). The sections use the repository + [machine](https://github.com/building-envelope-data/machine). +1. Within the project [machine](https://github.com/building-envelope-data/machine), + create a user for restricted areas like staging and email, for example with + `./deploy.mk user NAME=userRestrictedAreas`. +1. Register as metabase user + https://www.local.buildingenvelopedata.org:7001. +1. Use your account for restricted areas to open + https://www.local.buildingenvelopedata.org:7001/email/ . Open the registration email and use the link to confirm your metabase user account. +1. [Login in](https://www.local.buildingenvelopedata.org:7001/users/login) with + your metabase account. +1. [Create an institution](https://www.local.buildingenvelopedata.org:7001/institutions/create). + Use the UUID of the institution to verify the pending institution with + ``` + + ``` +1. Add a component, a method, a data format and a database to this institution. The database must include the URL of the GraphQL endpoint e.g. https://www.local.solarbuildingenvelopes.com:7501/graphql/ . Copy the UUIDs of the database and of your institution and paste it into the .env file of your `database` project. In the folder of your database, run `make down && make build up`. Sign in on https://www.local.solarbuildingenvelopes.com:7501/ with your metabase account. Create an optical dataset on https://www.local.solarbuildingenvelopes.com:7501/graphql/ using the mutation `createOpticalData`. List all pending optical datasets with the query `allPendingOpticalData`. Publish your optical dataset with the mutation `publishData`. Search your database for your optical dataset e.g. with the query `allOpticalData`. Search the metabase for your optical dataset e.g. with the query `databases{edges{node{allOpticalData`. \ No newline at end of file From 2eecf5a329ead556bcd7a16d6464561773b1996a Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Tue, 12 May 2026 18:10:48 +0200 Subject: [PATCH 02/10] first steps of the tutorial --- .../interaction_metabase_database.md | 43 ++++++++++++++++++- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 66e1b2ee4..386ec16e3 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -1,13 +1,52 @@ # Test the interaction of metabase and database +This tutorial explains how you can test the interaction of metabase and +database using the frontend as graphical user interface. For convenience, +the GraphQL queries and mutations are added at the beginning of each step. If something should +fail in the frontend, use the GraphQL endpoint of the backend. + +This tutorial can be used to validate your setup in a) `develop`, b) `staging` and c) `production`. For example + +## Prepare + 1. Follow the sections `Getting Started` of [metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) and [database](https://github.com/building-envelope-data/database?tab=readme-ov-file#getting-started). The sections use the repository [machine](https://github.com/building-envelope-data/machine). 1. Within the project [machine](https://github.com/building-envelope-data/machine), create a user for restricted areas like staging and email, for example with `./deploy.mk user NAME=userRestrictedAreas`. -1. Register as metabase user - https://www.local.buildingenvelopedata.org:7001. + +## Quick test + +1. `loginUser`: Use the username `administrator@buildingenvelopedata.org` and + the `BOOTSTRAP_USER_PASSWORD` which you find in `./.env` to sign in as admin at the metabase. + - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login + - b) https://staging.buildingenvelopedata.org/connect/client/login + - c) https://www.buildingenvelopedata.org/connect/client/login +1. `createInstitution`: Create a new institution. + - a) https://www.local.buildingenvelopedata.org:7001/institutions + - b) https://staging.buildingenvelopedata.org/institutions + - c) https://www.buildingenvelopedata.org/institutions +1. Save the `institutionId` of the new institution and open its page. Apply the + next steps on that page. + - a) https://www.local.buildingenvelopedata.org:7001/institutions/${instituionId} + - b) https://staging.buildingenvelopedata.org/institutions/${instituionId} + - c) https://www.buildingenvelopedata.org/institutions/${instituionId} +1. `createComponent`: Create a new component which is manufactured by your new + institution. Save the `componentId`. +1. `createMethod`: Create a new method which is managed by your new institution. + Save the `methodId`. +1. `createDataFormat`: Create a new data format which is managed by your new + institution. Save the `dataFormatId`. + +######Create dataset. Find dataset. + +## Detailed test + +1. `registerUser`: Register as new user at the metabase. + a) https://www.local.buildingenvelopedata.org:7001/users/register + b) https://staging.buildingenvelopedata.org/users/register + c) https://www.buildingenvelopedata.org/users/register 1. Use your account for restricted areas to open https://www.local.buildingenvelopedata.org:7001/email/ . Open the registration email and use the link to confirm your metabase user account. 1. [Login in](https://www.local.buildingenvelopedata.org:7001/users/login) with From 812758501e6b48009cc70d6366cd853bffd6be48 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 13 May 2026 12:35:34 +0200 Subject: [PATCH 03/10] Write the first two parts of the tutorial --- .../interaction_metabase_database.md | 112 ++++++++++++++++-- 1 file changed, 102 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 386ec16e3..7fbc4b029 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -1,28 +1,47 @@ # Test the interaction of metabase and database This tutorial explains how you can test the interaction of metabase and -database using the frontend as graphical user interface. For convenience, -the GraphQL queries and mutations are added at the beginning of each step. If something should -fail in the frontend, use the GraphQL endpoint of the backend. +database using the frontend as graphical user interface. -This tutorial can be used to validate your setup in a) `develop`, b) `staging` and c) `production`. For example +For convenience, the GraphQL queries and mutations are added at the beginning of each step. If something should fail in the frontend, use the GraphQL endpoint of the backend. -## Prepare +This tutorial can be used to validate your setup in a) `develop`, b) `staging` and c) `production`. If there is a difference between the three cases, it is described for a) , b) and c). -1. Follow the sections `Getting Started` of [metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) +## Prepare for the tutorial + +1. Create the product data network with a `metabase` and a `database`. + - a) Follow the sections `Development>Getting Started` of [metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) + and [database](https://github.com/building-envelope-data/database?tab=readme-ov-file#getting-started). The sections use the repository + [machine](https://github.com/building-envelope-data/machine). + - b) and c) Follow the sections `Deployment>Setting up a production machine` of [metabase](https://github.com/building-envelope-data/metabase?tab=readme-ov-file#getting-started) and [database](https://github.com/building-envelope-data/database?tab=readme-ov-file#getting-started). The sections use the repository [machine](https://github.com/building-envelope-data/machine). -1. Within the project [machine](https://github.com/building-envelope-data/machine), +1. Within each project [machine](https://github.com/building-envelope-data/machine), create a user for restricted areas like staging and email, for example with `./deploy.mk user NAME=userRestrictedAreas`. -## Quick test +## Search `database` via `metabase` + +This works if your `database` contains an optical dataset and is connected to the `metabase`. +1. Open the frontend of the `metabase`. + - a) https://www.local.buildingenvelopedata.org:7001 + - b) https://staging.buildingenvelopedata.org + - c) https://www.buildingenvelopedata.org +1. `allOpticalData`: Click on `Data>Optical Data`. If you find your optical + dataset there, the connection between `metabase` and `database` works. + - a) https://www.local.buildingenvelopedata.org:7001/data/optical + - b) https://staging.buildingenvelopedata.org/data/optical + - c) https://www.buildingenvelopedata.org/data/optical + +## Create a dataset as admin 1. `loginUser`: Use the username `administrator@buildingenvelopedata.org` and - the `BOOTSTRAP_USER_PASSWORD` which you find in `./.env` to sign in as admin at the metabase. + the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in `./.env` to sign in as admin at the metabase. Click on `Administrator` - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login - b) https://staging.buildingenvelopedata.org/connect/client/login - c) https://www.buildingenvelopedata.org/connect/client/login +1. Click on `Administrator>Profile` and save the UUID of this user. You will + need it later as `creatorId`. 1. `createInstitution`: Create a new institution. - a) https://www.local.buildingenvelopedata.org:7001/institutions - b) https://staging.buildingenvelopedata.org/institutions @@ -38,9 +57,82 @@ This tutorial can be used to validate your setup in a) `develop`, b) `staging` a Save the `methodId`. 1. `createDataFormat`: Create a new data format which is managed by your new institution. Save the `dataFormatId`. +1. `loginUser`: Switch to the database. Use the username + `administrator@buildingenvelopedata.org` and the `BOOTSTRAP_USER_PASSWORD` + which you find in your project `database` in ./.env` to sign in as admin at the database. + - a) https://www.local.solarbuildingenvelopes.com:7001/connect/client/login + - b) https://staging.solarbuildingenvelopes.com/connect/client/login + - c) https://www.solarbuildingenvelopes.com/connect/client/login +1. Open the GraphQL endpoint of the `database`. + - a) https://www.local.solarbuildingenvelopes.com:7001/graphql + - b) https://staging.solarbuildingenvelopes.com/graphql + - c) https://www.solarbuildingenvelopes.com/graphql +1. Copy the attached mutation into the field `Request`. Replace the UUIDs by + your saved `componentId`, `methodId`, `creatorId` and `dataFormatId`. Click + on `Run`. You have successfully created the dataset if the response contains + `"errors": null`. If not, please follow the error messages. + ``` + mutation { + createOpticalData( + input: { + name: "Optical dataset for testing purposes" + componentId: "7cedc6f7-89d4-4b1d-9215-743b283b2102" + appliedMethod: { + arguments: [] + methodId: "907e3366-08ea-478c-ae33-6086938508ba" + sources: [] + } + cielabColors: [] + colorRenderingIndices: [] + createdAt: "2026-05-12T13:45:30.000Z" + creatorId: "5320d6fb-b96d-4aeb-a24c-eb7036d3437a" + description: "This optical dataset is only used for testing purposes" + infraredEmittances: [] + locale: "en-US" + nearnormalHemisphericalSolarReflectances: [0.1,0.1] + nearnormalHemisphericalSolarTransmittances: [0.7,0.7] + nearnormalHemisphericalVisibleReflectances: [0.1,0.1] + nearnormalHemisphericalVisibleTransmittances: [0.7,0.7] + rootResource: { + archivedFilesMetaInformation: [] + description: "BED-JSON" + dataFormatId: "7e302757-0f43-4469-b058-b9c5a1f9f29a" + } + warnings: [] + } + ) { + opticalData { + uuid + resourceTree{ + root { + value { + archivedFilesMetaInformation { + dataFormatId + path + } + description + dataFormatId + hashValue + id + locator + uuid + } + vertexId + } + } + } + errors { + code + message + path + } + } + } + ``` +1. Follow the instructions of the section [Search `database` via `metabase`](#search-database-via-metabase). -######Create dataset. Find dataset. +######### ## Detailed test 1. `registerUser`: Register as new user at the metabase. From 1504845ba72646547891d4a36990c5ae786dd5ad Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 13 May 2026 13:45:02 +0200 Subject: [PATCH 04/10] Add `publishData` --- .../interaction_metabase_database.md | 89 ++++++++++++++----- 1 file changed, 66 insertions(+), 23 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 7fbc4b029..37e6353c8 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -67,10 +67,11 @@ This works if your `database` contains an optical dataset and is connected to th - a) https://www.local.solarbuildingenvelopes.com:7001/graphql - b) https://staging.solarbuildingenvelopes.com/graphql - c) https://www.solarbuildingenvelopes.com/graphql -1. Copy the attached mutation into the field `Request`. Replace the UUIDs by - your saved `componentId`, `methodId`, `creatorId` and `dataFormatId`. Click - on `Run`. You have successfully created the dataset if the response contains - `"errors": null`. If not, please follow the error messages. +1. `createOpticalData`: Copy the attached mutation into the field `Request`. + Replace the UUIDs by your saved `componentId`, `methodId`, `creatorId` and + `dataFormatId`. Click on `Run`. You have successfully created the dataset if + the response contains `"errors": null`. If not, please follow the error + messages. ``` mutation { createOpticalData( @@ -78,9 +79,9 @@ This works if your `database` contains an optical dataset and is connected to th name: "Optical dataset for testing purposes" componentId: "7cedc6f7-89d4-4b1d-9215-743b283b2102" appliedMethod: { - arguments: [] - methodId: "907e3366-08ea-478c-ae33-6086938508ba" - sources: [] + arguments: [] + methodId: "907e3366-08ea-478c-ae33-6086938508ba" + sources: [] } cielabColors: [] colorRenderingIndices: [] @@ -94,9 +95,9 @@ This works if your `database` contains an optical dataset and is connected to th nearnormalHemisphericalVisibleReflectances: [0.1,0.1] nearnormalHemisphericalVisibleTransmittances: [0.7,0.7] rootResource: { - archivedFilesMetaInformation: [] - description: "BED-JSON" - dataFormatId: "7e302757-0f43-4469-b058-b9c5a1f9f29a" + archivedFilesMetaInformation: [] + description: "BED-JSON" + dataFormatId: "7e302757-0f43-4469-b058-b9c5a1f9f29a" } warnings: [] } @@ -104,21 +105,16 @@ This works if your `database` contains an optical dataset and is connected to th opticalData { uuid resourceTree{ - root { - value { - archivedFilesMetaInformation { - dataFormatId - path + root { + value { + description + dataFormatId + hashValue + id + locator + uuid } - description - dataFormatId - hashValue - id - locator - uuid } - vertexId - } } } errors { @@ -129,6 +125,53 @@ This works if your `database` contains an optical dataset and is connected to th } } ``` +1. The response should be similar to the attached response. Save `uuid` of the + dataset `data/createOpticalData/opticalData/uuid` and the `uuid` of the resource `data/createOpticalData/opticalData/resourceTree/root/value/uuid`. + ``` + { + "data": { + "createOpticalData": { + "opticalData": { + "uuid": "e8783902-9895-4b94-bf14-a7f48de1dcb6", + "resourceTree": { + "root": { + "value": { + "description": "BED-JSON", + "dataFormatId": "7e302757-0f43-4469-b058-b9c5a1f9f29a", + "hashValue": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855", + "id": "R2V0SHR0cHNSZXNvdXJjZTp+YTL727lDQLixD+GDQw4y", + "locator": "https://www.solar-in-the-facade.com/api/resources/fb32617e-b9db-4043-b8b1-0fe183430e32", + "uuid": "fb32617e-b9db-4043-b8b1-0fe183430e32" + } + } + } + }, + "errors": null + } + } + } + ``` +1. `publishData`: Open a new document in the GraphQL endpoint and copy the + attached mutation into the field `Request`. Replace the uuid of the `dataId` + by the `uuid` of the dataset. Click on `Run` to publish you pending dataset. + If the response contains `"errors": null`, you have been successful. If not, + please follow the error messages. + ``` + mutation { + publishData( + input: { + dataId: "4d9a00cd-6146-4f2b-8dbc-dc6b01a37037" + dataKind: OPTICAL_DATA + } + ) { + errors { + code + message + path + } + } + } + ``` 1. Follow the instructions of the section [Search `database` via `metabase`](#search-database-via-metabase). From 9764e721a975b1d61b068abc9ef64eceeb4dd416 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 13 May 2026 16:23:43 +0200 Subject: [PATCH 05/10] Start with `Register as new user` --- .../interaction_metabase_database.md | 190 +++++++++++++++++- 1 file changed, 180 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 37e6353c8..f957e2296 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -36,7 +36,7 @@ This works if your `database` contains an optical dataset and is connected to th ## Create a dataset as admin 1. `loginUser`: Use the username `administrator@buildingenvelopedata.org` and - the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in `./.env` to sign in as admin at the metabase. Click on `Administrator` + the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in `./.env` to sign in as admin at the metabase. - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login - b) https://staging.buildingenvelopedata.org/connect/client/login - c) https://www.buildingenvelopedata.org/connect/client/login @@ -174,16 +174,33 @@ This works if your `database` contains an optical dataset and is connected to th ``` 1. Follow the instructions of the section [Search `database` via `metabase`](#search-database-via-metabase). - -######### -## Detailed test +## Register as new user 1. `registerUser`: Register as new user at the metabase. - a) https://www.local.buildingenvelopedata.org:7001/users/register - b) https://staging.buildingenvelopedata.org/users/register - c) https://www.buildingenvelopedata.org/users/register -1. Use your account for restricted areas to open - https://www.local.buildingenvelopedata.org:7001/email/ . Open the registration email and use the link to confirm your metabase user account. + - a) https://www.local.buildingenvelopedata.org:7001/users/register + - b) https://staging.buildingenvelopedata.org/users/register + - c) https://www.buildingenvelopedata.org/users/register +1. Confirm your account by opening a link in a browser. + - a) Use your account for restricted areas to open + https://www.local.buildingenvelopedata.org:7001/email/ . Open the registration email and use the link to confirm your account. + - b) Use your account for restricted areas to open + https://staging.buildingenvelopedata.org/email/ . Open the registration + email and use the link to confirm your metabase user account. + - c) Open the registration email in your mailbox and use the link to confirm + your account. +1. Use your account to follow the instructions of the section [Create a dataset + as admin](#create-a-dataset-as-admin), but with the following changes: +1. `verifyInstitution`: After the step `createInstitution`, log out of your + account and login as `administrator@buildingenvelopedata.org` with the + `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in + `./.env`. + +ooo + +1. `loginUser`: Use your account to sign in as admin at the metabase. Click on `Administrator` + - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login + - b) https://staging.buildingenvelopedata.org/connect/client/login + - c) https://www.buildingenvelopedata.org/connect/client/login 1. [Login in](https://www.local.buildingenvelopedata.org:7001/users/login) with your metabase account. 1. [Create an institution](https://www.local.buildingenvelopedata.org:7001/institutions/create). @@ -191,4 +208,157 @@ This works if your `database` contains an optical dataset and is connected to th ``` ``` -1. Add a component, a method, a data format and a database to this institution. The database must include the URL of the GraphQL endpoint e.g. https://www.local.solarbuildingenvelopes.com:7501/graphql/ . Copy the UUIDs of the database and of your institution and paste it into the .env file of your `database` project. In the folder of your database, run `make down && make build up`. Sign in on https://www.local.solarbuildingenvelopes.com:7501/ with your metabase account. Create an optical dataset on https://www.local.solarbuildingenvelopes.com:7501/graphql/ using the mutation `createOpticalData`. List all pending optical datasets with the query `allPendingOpticalData`. Publish your optical dataset with the mutation `publishData`. Search your database for your optical dataset e.g. with the query `allOpticalData`. Search the metabase for your optical dataset e.g. with the query `databases{edges{node{allOpticalData`. \ No newline at end of file +1. Add a component, a method, a data format and a database to this institution. The database must include the URL of the GraphQL endpoint e.g. https://www.local.solarbuildingenvelopes.com:7501/graphql/ . Copy the UUIDs of the database and of your institution and paste it into the .env file of your `database` project. In the folder of your database, run `make down && make build up`. Sign in on https://www.local.solarbuildingenvelopes.com:7501/ with your metabase account. Create an optical dataset on https://www.local.solarbuildingenvelopes.com:7501/graphql/ using the mutation `createOpticalData`. List all pending optical datasets with the query `allPendingOpticalData`. Publish your optical dataset with the mutation `publishData`. Search your database for your optical dataset e.g. with the query `allOpticalData`. Search the metabase for your optical dataset e.g. with the query `databases{edges{node{allOpticalData`. + + +## Draft from C3RRO + +## Add Data to BED - Database + +## 1. To Sync with Metabase: First add Component on metabase! + +Using the UI buildingenvelopedata.org is okay: +- Login with your account +- Go to your Institution +- Go to Managed Components +- Insert Name, Description, … +- Click on Create +- Save the CompoentID you get in the message box after creation! + +## 2. Make sure everything is prepared + +At least necessary: + +| entity | description | +|--------|----------| +| name | | +| description | | +| componentId | Uuid you get from the metabase in the step before | +| creatorId | Uuid of your institution | +| locale | e.g. "en-US" | +| appliedMethod -> methodId | Uuid of the method used to create the data | +| rootResource -> dataFormatId | Uuid of the Data format | + +And also the data file itself ( a json file with data folowing the hygrothermalData schema in that case ) + + +## 3. Create Data +Don't forget to query at least for the hygrothermalData->uuid and for hygrothermalData->resources->uuid + +```json +mutation createHygrothermalDataMineralWool { + C3rro: createHygrothermalData( + input: { + name: "Mineral Wool" + componentId: "dde8c5e2-ebc4-469f-b6fb-a58b1cd8b76f" + creatorId: "a11b2f32-a270-4caf-8eae-1d47ebba3274" + description: "Generic Hygrothermal Data for Mineral Wool" + locale: "en-US" + warnings: [] + appliedMethod: { methodId: "b2b3f1fd-fb17-4219-a4f6-18dbd6d25ecd", sources: [], arguments: [] } + rootResource: { + archivedFilesMetaInformation: { dataFormatId: "9ca9e8f5-94bf-4fdd-81e3-31a58d7ca708", path: "JSON" } + dataFormatId: "9ca9e8f5-94bf-4fdd-81e3-31a58d7ca708" + description: "" + } + createdAt: "2025-10-14T13:00:00+01:00" + } + ) { + errors { + code + message + path + } + hygrothermalData { + componentId + createdAt + creatorId + databaseId + description + id + locale + name + timestamp + uuid + warnings + resources { + uuid + locator + } + } + } +} +``` + +## 4. Upload the Data +- Go to your database frontend +- use the hygrothermalData->resources->uuid you get in the add Data step. +- Select your file with the data + +## 5. Publish data +Use the hygrothermalData->uuid given in the response from the add Data step + +```json +mutation pubishDataset { + publishData(input: { + dataId: "ca28833d-224d-4f8e-a14e-a755f1afe37d", + dataKind: HYGROTHERMAL_DATA + }) { + errors { + code + message + path + } + query { + hasCalorimetricData + hasGeometricData + hasHygrothermalData + hasLifeCycleData + hasOpticalData + hasPhotovoltaicData + verificationCode + } + } +} +``` + +## 6. Setting Access + +| entitiy | description | +|---------|-------------| +| allowedUserAndQuantity->key | Uuid of an specific user | +| allowedUserAndQuantity->value | Count ?? | +| allowedInstitutions | Uuid of an insitution | +| allowedApplications | Uuid of an OpenId Connect Applications | + +```json +mutation accessControl { + updateDataAccessRights( + input: { + allowedUserAndQuantity: { + key: null, + value: null + } + dataId: "8ba511f7-3410-49fa-a237-20cb9ee308be" + dataKind: HYGROTHERMAL_DATA + allowedInstitutions: null + allowedApplications: null + } + ) { + errors { + code + message + path + } + query { + verificationCode + currentUser { + id + name + subject + uuid + } + } + } +} +``` \ No newline at end of file From 660ae25878fef02cf14868c30437ca38d727b377 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 13 May 2026 16:42:38 +0200 Subject: [PATCH 06/10] minor progress --- .../interaction_metabase_database.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index f957e2296..450de09f3 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -189,11 +189,20 @@ This works if your `database` contains an optical dataset and is connected to th - c) Open the registration email in your mailbox and use the link to confirm your account. 1. Use your account to follow the instructions of the section [Create a dataset - as admin](#create-a-dataset-as-admin), but with the following changes: -1. `verifyInstitution`: After the step `createInstitution`, log out of your - account and login as `administrator@buildingenvelopedata.org` with the - `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in - `./.env`. + as admin](#create-a-dataset-as-admin), but with the following change: + - `verifyInstitution`: After the step `createInstitution`, log out of + your account and login as `administrator@buildingenvelopedata.org` with + the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in + `./.env`. Verify the newly created institution. + +## Add a new database + +1. `loginUser`: Use the username `administrator@buildingenvelopedata.org` and + the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in `./.env` to sign in as admin at the metabase. + - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login + - b) https://staging.buildingenvelopedata.org/connect/client/login + - c) https://www.buildingenvelopedata.org/connect/client/login +1. `createDatabase`: ooo From 7fa1ac772e97867f61a5f67d5d3c8e25b548be1f Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Wed, 13 May 2026 17:40:09 +0200 Subject: [PATCH 07/10] minor progress --- docs/tutorials/interaction_metabase_database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 450de09f3..d4a9d9427 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -193,7 +193,7 @@ This works if your `database` contains an optical dataset and is connected to th - `verifyInstitution`: After the step `createInstitution`, log out of your account and login as `administrator@buildingenvelopedata.org` with the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in - `./.env`. Verify the newly created institution. + `./.env`. Verify the newly created institution. Then log out and log in with your account. ## Add a new database From c61de304c6bb36c369fe76e9f47b1fa97aa23a3f Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Tue, 19 May 2026 09:47:43 +0200 Subject: [PATCH 08/10] Create database as new user --- docs/tutorials/interaction_metabase_database.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index d4a9d9427..1fced41c4 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -197,8 +197,8 @@ This works if your `database` contains an optical dataset and is connected to th ## Add a new database -1. `loginUser`: Use the username `administrator@buildingenvelopedata.org` and - the `BOOTSTRAP_USER_PASSWORD` which you find in your project `metabase` in `./.env` to sign in as admin at the metabase. +1. `loginUser`: After [registering as a new user](#register-as-new-user), sign in at the metabase with your account. + `administrator@buildingenvelopedata.org` or with your account as a new user. - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login - b) https://staging.buildingenvelopedata.org/connect/client/login - c) https://www.buildingenvelopedata.org/connect/client/login From de5564122c2971769f8c4aea0fc1798b566234dd Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Thu, 21 May 2026 15:24:38 +0200 Subject: [PATCH 09/10] Section `Add a new database` --- docs/tutorials/interaction_metabase_database.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 1fced41c4..6b24ee7d0 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -197,12 +197,19 @@ This works if your `database` contains an optical dataset and is connected to th ## Add a new database -1. `loginUser`: After [registering as a new user](#register-as-new-user), sign in at the metabase with your account. - `administrator@buildingenvelopedata.org` or with your account as a new user. +1. `loginUser`: After [registering as a new user](#register-as-new-user), sign + in at the metabase with your account. - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login - b) https://staging.buildingenvelopedata.org/connect/client/login - c) https://www.buildingenvelopedata.org/connect/client/login -1. `createDatabase`: +1. `createDatabase`: Go to your institution - either with the tab + `Institutions` or your user `Profile`. Switch to the tab + `Operated Databases` and click on `New Database`. Enter all required fields including the `Locator` which is the URL of the GraphQL endpoint of your database. Click on `Create`. +1. Stay in the tab `Operated Databases` and click on your pending database. + Take the verification code and update your database so that it returns this + verification code when receiving the GraphQL `query { verificationCode }`. + This proves that you control the new database. Then, press the “Verify” button. + ooo From 23929d40e43f93befa73446523729e6a48097760 Mon Sep 17 00:00:00 2001 From: christoph-maurer Date: Thu, 21 May 2026 15:57:21 +0200 Subject: [PATCH 10/10] Next step: Set the access to a dataset --- .../interaction_metabase_database.md | 138 ++---------------- 1 file changed, 10 insertions(+), 128 deletions(-) diff --git a/docs/tutorials/interaction_metabase_database.md b/docs/tutorials/interaction_metabase_database.md index 6b24ee7d0..fa46b83a8 100644 --- a/docs/tutorials/interaction_metabase_database.md +++ b/docs/tutorials/interaction_metabase_database.md @@ -19,6 +19,8 @@ This tutorial can be used to validate your setup in a) `develop`, b) `staging` a 1. Within each project [machine](https://github.com/building-envelope-data/machine), create a user for restricted areas like staging and email, for example with `./deploy.mk user NAME=userRestrictedAreas`. +1. When you are not sure about the meaning of a term, consult the [API + specification of the metabase](https://github.com/building-envelope-data/api/blob/develop/apis/metabase.graphql) and the [API specification of product data servers](https://github.com/building-envelope-data/api/blob/develop/apis/database.graphql) which contain all details. ## Search `database` via `metabase` @@ -151,6 +153,12 @@ This works if your `database` contains an optical dataset and is connected to th } } ``` +1. `uploadFile`: In the frontend of the database, click on your user and + `Upload File`. Enter the uuid of the resource from the previous step and + upload the dataset, for example a JSON file. + - a) https://www.local.solarbuildingenvelopes.com:7501/upload-file + - b) https://staging.solarbuildingenvelopes.com/upload-file + - c) https://www.solarbuildingenvelopes.com/upload-file 1. `publishData`: Open a new document in the GraphQL endpoint and copy the attached mutation into the field `Request`. Replace the uuid of the `dataId` by the `uuid` of the dataset. Click on `Run` to publish you pending dataset. @@ -174,7 +182,7 @@ This works if your `database` contains an optical dataset and is connected to th ``` 1. Follow the instructions of the section [Search `database` via `metabase`](#search-database-via-metabase). -## Register as new user +## Register as new user and create an institution 1. `registerUser`: Register as new user at the metabase. - a) https://www.local.buildingenvelopedata.org:7001/users/register @@ -210,133 +218,7 @@ This works if your `database` contains an optical dataset and is connected to th verification code when receiving the GraphQL `query { verificationCode }`. This proves that you control the new database. Then, press the “Verify” button. - -ooo - -1. `loginUser`: Use your account to sign in as admin at the metabase. Click on `Administrator` - - a) https://www.local.buildingenvelopedata.org:7001/connect/client/login - - b) https://staging.buildingenvelopedata.org/connect/client/login - - c) https://www.buildingenvelopedata.org/connect/client/login -1. [Login in](https://www.local.buildingenvelopedata.org:7001/users/login) with - your metabase account. -1. [Create an institution](https://www.local.buildingenvelopedata.org:7001/institutions/create). - Use the UUID of the institution to verify the pending institution with - ``` - - ``` -1. Add a component, a method, a data format and a database to this institution. The database must include the URL of the GraphQL endpoint e.g. https://www.local.solarbuildingenvelopes.com:7501/graphql/ . Copy the UUIDs of the database and of your institution and paste it into the .env file of your `database` project. In the folder of your database, run `make down && make build up`. Sign in on https://www.local.solarbuildingenvelopes.com:7501/ with your metabase account. Create an optical dataset on https://www.local.solarbuildingenvelopes.com:7501/graphql/ using the mutation `createOpticalData`. List all pending optical datasets with the query `allPendingOpticalData`. Publish your optical dataset with the mutation `publishData`. Search your database for your optical dataset e.g. with the query `allOpticalData`. Search the metabase for your optical dataset e.g. with the query `databases{edges{node{allOpticalData`. - - -## Draft from C3RRO - -## Add Data to BED - Database - -## 1. To Sync with Metabase: First add Component on metabase! - -Using the UI buildingenvelopedata.org is okay: -- Login with your account -- Go to your Institution -- Go to Managed Components -- Insert Name, Description, … -- Click on Create -- Save the CompoentID you get in the message box after creation! - -## 2. Make sure everything is prepared - -At least necessary: - -| entity | description | -|--------|----------| -| name | | -| description | | -| componentId | Uuid you get from the metabase in the step before | -| creatorId | Uuid of your institution | -| locale | e.g. "en-US" | -| appliedMethod -> methodId | Uuid of the method used to create the data | -| rootResource -> dataFormatId | Uuid of the Data format | - -And also the data file itself ( a json file with data folowing the hygrothermalData schema in that case ) - - -## 3. Create Data -Don't forget to query at least for the hygrothermalData->uuid and for hygrothermalData->resources->uuid - -```json -mutation createHygrothermalDataMineralWool { - C3rro: createHygrothermalData( - input: { - name: "Mineral Wool" - componentId: "dde8c5e2-ebc4-469f-b6fb-a58b1cd8b76f" - creatorId: "a11b2f32-a270-4caf-8eae-1d47ebba3274" - description: "Generic Hygrothermal Data for Mineral Wool" - locale: "en-US" - warnings: [] - appliedMethod: { methodId: "b2b3f1fd-fb17-4219-a4f6-18dbd6d25ecd", sources: [], arguments: [] } - rootResource: { - archivedFilesMetaInformation: { dataFormatId: "9ca9e8f5-94bf-4fdd-81e3-31a58d7ca708", path: "JSON" } - dataFormatId: "9ca9e8f5-94bf-4fdd-81e3-31a58d7ca708" - description: "" - } - createdAt: "2025-10-14T13:00:00+01:00" - } - ) { - errors { - code - message - path - } - hygrothermalData { - componentId - createdAt - creatorId - databaseId - description - id - locale - name - timestamp - uuid - warnings - resources { - uuid - locator - } - } - } -} -``` - -## 4. Upload the Data -- Go to your database frontend -- use the hygrothermalData->resources->uuid you get in the add Data step. -- Select your file with the data - -## 5. Publish data -Use the hygrothermalData->uuid given in the response from the add Data step - -```json -mutation pubishDataset { - publishData(input: { - dataId: "ca28833d-224d-4f8e-a14e-a755f1afe37d", - dataKind: HYGROTHERMAL_DATA - }) { - errors { - code - message - path - } - query { - hasCalorimetricData - hasGeometricData - hasHygrothermalData - hasLifeCycleData - hasOpticalData - hasPhotovoltaicData - verificationCode - } - } -} -``` +ooooo ## 6. Setting Access