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..fa46b83a8 --- /dev/null +++ b/docs/tutorials/interaction_metabase_database.md @@ -0,0 +1,262 @@ +# 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`. If there is a difference between the three cases, it is described for a) , b) and c). + +## 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 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` + +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 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. 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 + - 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`. +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. `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( + 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 { + description + dataFormatId + hashValue + id + locator + uuid + } + } + } + } + errors { + code + message + path + } + } + } + ``` +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. `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. + 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). + +## 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 + - 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 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. Then log out and log in with your account. + +## Add a new database + +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`: 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. + +ooooo + +## 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