This service allows to run SQL queries on the database. In particular, this service allows users with limited permissions to see reports of aggregated statistics across all data (e.g. a supervisor could analyse reports without having access to possibly confidential details of participants or notes).
See the ndb-setup repo for full deployment instructions.
To use this you need a running CouchDB and structured query server (SQS).
The following variables might need to be configured in the .env
file:
DATABASE_URL
URL of theCouchDB
or replication backendQUERY_URL
URL of the SQSSCHEMA_CONFIG_ID
database ID of the document which holds the SQS schema (default_design/sqlite:config
)PORT
where the app should listen (default 3000)SENTRY_DSN
for remote logging
Reports and their results are available for external services through the given API endpoints (see OpenAPI specs). Endpoints require a valid JWT access token, which can be fetched via OAuth2 client credential flow.
- Request client_id and client_secret from server administrator (--> admin has to create new client grant in Keycloak)
- Get the realm of your instance (e.g. https://[your_realm].aam-digital.com). This is both the subdomain of systems hosted on aam-digital.com and the Keycloak Realm for authentication (case sensitive!).
- Get valid access token using your client secret:
curl -X "POST" "https://keycloak.aam-digital.net/realms/<your_realm>/protocol/openid-connect/token" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "client_id=<your_client_id>" \
--data-urlencode "client_secret=<your_client_secret>" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scopes=openid reports_read reports_write"
Check API docs for the required "scopes". This returns a JWT access token required to provided as Bearer Token for any request to the API endpoints. Sample token:
{
"access_token": "eyJhbGciOiJSUzI...",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "openid reports_read reports_write"
}
- Request the all available reports:
GET /reports
(see OpenAPI specs for details) - Trigger the calculation of a reports data:
POST /report-calculation/<report-id>
- Get status of the report calculation:
GET /report-calculation/<calculation-id>
- Once the status shows the calculation is completed, get the actual result data:
GET /report-calculation/<calculation-id>/data
- Create an initial webhook (if not already registered):
POST /webhook
- Register for events of the selected report:
POST /webhook/{webhookId}/subscribe/report/{reportId}:
- You will receive Event objects to your webhook, including an initial event directly after you subscribe, pointing to the current report data
- Use the report-calculation-id in the event to fetch actual data from /report-calculation endpoint