Data Retrieval
Promote a dashboard to the next environment
Check, then publish a dashboard from one environment to the next, for example from staging to production.
A release copies a dashboard and its metrics from its workspace to the linked workspace of the next environment. Every call is a dry run unless you send "dryRun": false.
Before you start
- You have a service token. See Authentication.
- An admin linked two or more workspaces as environments in Settings > Environments.
Steps
-
Run a dry run:
curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases \ --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "workspaceName": "Staging", "dashboardId": "sales-overview" }' -
Read
data.checks,data.metricsanddata.canPublish. Each metric'sactionisadded,updated,retiredorunchanged. Copydata.expectedVersion. -
Publish with the version:
curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-releases \ --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "workspaceName": "Staging", "dashboardId": "sales-overview", "dryRun": false, "expectedVersion": "<data.expectedVersion from step 1>", "message": "Add churn chart", "tag": "v12" }'
You get the release id. Next, list releases.
ServiceTokenAuthorizationBearer <token>A service token. A data app API token is refused.
Body
The workspace the dashboard is in now.
The dashboard's externalDashboardId
Required to publish. The expectedVersion of your dry run. If the dashboard changed since, you get 409 LIVE_CHANGED
A label, up to 40 characters.
An https URL that gets a signed POST after the publish. See below.
Response
Dry run:
{ "data": { "sourceDashboardId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "target": { "environment": "Production", "externalDashboardId": "sales-overview", "isNew": false }, "summary": { "added": 1, "updated": 2, "retired": 0, "unchanged": 5 }, "metrics": [{ "name": "Churn", "action": "added" }], "checks": [], "canPublish": true, "noChanges": false, "expectedVersion": "9f2c..." }}Publish:
{ "data": { "releaseId": "0a1b2c3d-...", "shortId": "r-8k2m", "dashboardId": "...", "summary": { "added": 1, "updated": 2, "retired": 0, "unchanged": 5 } } }With callbackUrl, the response also has callback: { "delivered": true, "status": 200 }.
Callback
Databrain sends POST <callbackUrl> with { "id", "type": "release.published", "createdAt", "data": { ... } } and the header Databrain-Signature: t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256 of <t>.<body>, keyed with your service token. The URL must be https on a public host. Databrain waits 10 seconds and does not follow redirects. A failed callback does not undo the release.
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | WORKSPACE_NOT_FOUND | No workspace, or more than one, has this name |
| 400 | EXPECTED_VERSION_REQUIRED | You published without expectedVersion |
| 400 | INVALID_CALLBACK_URL | callbackUrl is not a public https URL |
| 403 | AUTH_ERROR | A service token is required. |
| 403 | FEATURE_NOT_ENABLED | Dashboard environments are not on for your company. |
| 404 | DASHBOARD_NOT_FOUND | No dashboard in the workspace has this id |
| 409 | LIVE_CHANGED | The dashboard changed after your dry run. Run it again |
| 409 | NO_CHANGES | Nothing to promote. Both environments match. |
| 409 | CLIENT_DASHBOARD | Customer dashboards cannot be promoted |
| 422 | CHECKS_FAILED | Fix the failed checks first. The body has checks |
| 500 | INTERNAL_SERVER_ERROR | Nothing was changed. Try again. |
For errors that every endpoint returns, see Authentication.
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/dashboard-releases' \ -H 'Content-Type: application/json' \ -d '{ "workspaceName": "string", "dashboardId": "string"}'{ "data": { "releaseId": "0a1b2c3d-...", "shortId": "r-8k2m", "dashboardId": "...", "externalDashboardId": "sales-overview", "summary": { "added": 1, "updated": 2, "retired": 0, "unchanged": 5 }, "callback": { "delivered": true, "status": 200 } }}