Skip to content

General Information

This page lists information to access the API that is relevant for all endpoints.

Authentication

Authentication in QVANTUM relies upon the OpenID Connect protocol, being a simple identity layer on top of the OAuth 2.0 protocol. For third-party client authentication with the QVANTUM Public API, we particularly employ the OAuth 2.0 Password Grant. A valid access token is prerequisite to any use of the QVANTUM Public API. Such a token can be acquired in exchange for a set of credentials valid within the tenant context. The respective authentication request includes details such as tenant id, client id, credentials, and a fixed grant type.

curl -X POST \
  -H "Content-Type:application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=${CLIENTID}" \
  -d "username=${USERNAME}" \
  -d "password=${PASSWORD}" \
  "${AUTH}/auth/realms/${TENANT}/protocol/openid-connect/token"

In case of a successful authentication, the response body will include a JSON payload like the following. Most importantly, the payload includes an access token, which will be required in all subsequent calls to the QVANTUM Public API. For the rest of this tutorial, the environment variable TOKEN represents the value for a valid access token gathered by this initial request. By default, all access tokens will expire after 5 minutes. For refreshing an access token, the response also includes a refresh token, expiring after 30 minutes.

{
  "access_token": "<TOKEN>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<REFRESH_TOKEN>",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "7f97c7ba-aac8-4a26-854b-ecd833b67ac3",
  "scope": "profile email add_audience_plankit-service"
}

For all subsequent requests to the QVANTUM Public API, access token information is passed as Authorization header with value Bearer ${TOKEN}.

The QVANTUM Public API is designed as a REST-style API following the HATEOAS principle. As such, endpoints represent resources relevant in a planning application domain. Besides resource-specific information, each resource also includes a set of links to itself and other resources, thus allowing navigation by following links in series of requests. The typical navigation starts with the tenant as entry point, then follows a link to a planning application under this tenant, and in turn follows a link to a cube under this planning application. Navigation to further resources not explicitly documented here follows the same principle.

With the availability of an access token, navigation starts with a request to the tenants resource, representing the list of all available tenant resources. The access token is passed via an authentication header Authorization with value Bearer ${TOKEN}, acquired during authentication.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants'

The response payload includes a JSON representation of a one-element list of tenant representations. Besides an id, display name, and description, a tenant resource includes the following links:

  • allPlanningApplications: a link to a collection of all planning application resources
  • planningApplications: an array of links to the planning application resources.
  • allUsers: retrieval link for user definition (cf. retrieve user definition)
  • userUploads: upload link for user definition (cf. upload user definition)
  • planning-app: link to planning web application

Important

Previous versions of this document incorrectly suggested that planningApplications is always a single link.

{
  "tenants":[
    {
      "id":1,
      "displayName":"My Tenant",
      "description":"A tenant for me.",
      "_links":{
        "self": {
          "href":"https://api.qvantum-plan.de/api/1/tenants/1"
        },
        "allPlanningApplications":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications"
        },
        "planningApplications":[
          {
            "href":"https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
          }
        ],
        "allUsers":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/users{?includeControllers}",
          "templated": true
        },
        "userUploads":{
          "href":"https://api.qvantum-plan.de/api/v1/tenants/1/userUploads"
        },
        "planning-app":{
          "href":"https://app.qvantum-plan.de/thinking-networks/"
        }
      }
    }
  ]
}

Within a tenant, QVANTUM supports a collection of planning applications. The allPlanningApplications link will return this collection. Currently, this is limited to one planning application. Alternatively, starting from a tenant resource, following a link in the planningApplications array provides a shortcut to the URL of the planning application resource. A request to this resource provides information about the respective planning application, including further navigation links.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants/1/planningApplications/1'

The response payload includes a JSON representation of the planning application resource. Besides an id, display name and description, a planning application resource includes the following links:

  • owner: owning tenant
  • uploads: endpoint for planning model metadata (cf. upload planning model).
  • allCubes: list of all cube resources within this planning application
  • allPermissions: upload resp. retrieval link for permission assignment (cf. upload permission assignment resp. retrieve permission assignment)
  • allWorkflowInstances: list of all workflow instance resources within this planning application
  • structuresUploads: endpoint can be used to upload structures

Planning Application JSON Representation

{
  "id": 1,
  "displayName": "My Planning Application",
  "description": "A planning application for me.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
    },
    "owner":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1"
    },
    "uploads":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/uploads"
    },
    "allCubes":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes"
    },
    "allPermissions": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/permissions"
    },
    "allWorkflowInstances": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/workflowInstances"
    }
    "structuresUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/structuresUploads"
    }
  }
}

Within a planning application, QVANTUM supports a set of cubes. As for planning applications within tenants, this set is currently limited to one cube per planning application. Starting from a planning application resource, following the link allCubes leads to a cube collection resource, listing all available cubes.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants/1/planningApplications/1/cubes'
curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants/1/planningApplications/1/cubes/1'

The response payload includes a JSON representation of a one-element array of cube representations. Besides an id, business key, display name, and description, each cube representation includes the following links:

{
  "id": 1,
  "businessKey": "MYCUBE",
  "displayName": "My Cube",
  "description": "A cube for me.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1"
    },
    "planningApplication":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
    },
    "dimensions":[
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/1"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/2"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/3"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/4"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/5"},
      {"href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/6"}
    ],
    "keyFigures": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/keyFigures"
    },
    "keyFiguresUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/keyFigures/uploads"
    },
    "dataUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dataUploads"
    },
    "data":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/cells{?dimensionRestrictions,inputAllowedFilter}"
    },
    "template":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/template"
    },
    "modelUploads": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/modelUploads"
    },
    "allExternalForms": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/forms"
    }
  }
}

A cube is substantial part of the model behind a planning application. A cube mainly consists of a set of dimensions. Detailed information on the structure of a planning model is available in section Planning model definition.

Starting from a cube, following one of the dimension links leads to a dimension resource.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  "${API}/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/1"

The response payload includes a JSON representation of a single dimension. Besides an id, business key, and description, each dimension representation includes singular and plural labels (singularName, pluralName) and a link structure enabling the navigation to the structure, defining the elements of a dimension (cf. next section).

{
  "id": 1,
  "businessKey": "KF",
  "singularName": "Key Figure",
  "pluralName": "Key Figures",
  "description": "A dimension for key figures.",
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/cubes/1/dimensions/1"
    },
    "cube":{
      "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/planningApplications/1/cubes/1"
    },
    "structure":{
        "href": "https://api-stage-qvantum.sw.buhl-data.com/api/v1/tenants/1/planningApplications/1/structures/1"
    }
  }
}

Conceptually, each dimension is defined by an underlying structure and its elements.

Starting from a dimension, following the structure link leads to a structure resource.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  "${API}/api/v1/tenants/1/planningApplications/1/structures/1"

The response payload includes a JSON representation of a structure. Besides an id, business key, display name, description and further properties, each structure representation includes a link upload, allowing the upload of planning application updates, in particular updates on the structure and the dimension based on it (cf. updating planning applications).

{
  "id": 1,
  "businessKey": "COSTCENTERS",
  "displayName": "Cost Centers",
  "description": "A structure defining a set of cost centers",
  ...
  "customAttributes": [
    {
      "businessKey": "COSTCENTERCLASS",
      "displayName": "Cost Center Class",
      "description": "Attribute to document different classes of cost centers",
      "attributeType": "TEXT"
    }
  ],
  "_links":{
    "self":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/structures/1"
    },
    "planningApplication":{
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
    },
    "upload": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/structures/1/upload"
    }
    ...
  }
}

Within a planning application, QVANTUM supports a workflow process. As for planning applications within tenants, this set is currently limited to one workflow instance per planning application. Starting from a planning application resource, following the link allWorkflowInstances leads to a collection resource, listing all available workflow instances.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants/1/planningApplications/1/workflowInstances'
curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  '${API}/api/v1/tenants/1/planningApplications/1/workflowInstances/1'

The response payload includes a JSON representation of a single worklflow instance. Besides an id, title and end date, the workflow instance representation includes a self link and a link to the underlying planning application. These fields may be updated by a separate request (cf. Update a Workflow)

{
  "id": 1,
  "title": "Financial Planning",
  "endDate": "2022-09-30T21:59:59Z",
  "status": "<WORKFLOW_STATUS>",
  "_links": {
    "self": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1/workflowInstances/1"
    },
    "planningApplication": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1/planningApplications/1"
    }
  }
}
The "status" field may have only these values:

  • NOT_STARTED : the workflow has not been started yet.
  • RUNNING : the workflow is running.
  • PAUSED : the workflow has been paused.
  • FINISHED: the workflow has been finished.
  • EXPORTED: the workflow has been finished and the data has been exported.

Localization

Some endpoints deliver localizable texts, e.g. log entries when uploading planning models. The desired locale can be specified using the Accept-Language header. Supported locales are en, de (default) and de-CH.

curl -i -X GET \
  -H "Authorization:Bearer ${TOKEN}" \
  -H "Accept-Language:en"
  "${PLANNING_APP_URL}/uploads/1"