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.

Authentication Request with curl

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.

Authentication Response JSON Payload

{
  "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.

Navigating to a Tenant¶

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.

Retrieve Tenant Information

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.

Tenant JSON Representation

{
  "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/"
        }
      }
    }
  ]
}

Navigating to a Planning Application¶

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.

Retrieve Planning Application Information

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)

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"
    }
  }
}

Navigating to a Cube¶

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.

Retrieve Cube List

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

Retrieve Single Cube

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:

dimensions: array of links to this cube's dimension resources.
keyFigures: export link for the key figures (cf. export key figures)
keyFiguresUploads: upload link for the key figures (cf. upload key figures)
dataUploads: upload link for cube cell data (cf. upload initial data)
data: download link for cube cell data (cf. export cell data / delete cell data)
template: download link to cube cell data template (cf. download data template)
modelUploads: upload link for full model updates (cf. upload full model update)
allExternalForms: import/export link for forms (cf. export and import forms)

Single Cube JSON Representation

{
  "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"
    }
  }
}

Navigating to a Dimension¶

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.

Retrieve Single Dimension

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).

Single Dimension JSON Representation

{
  "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"
    }
  }
}

Navigating to a Structure¶

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.

Retrieve Single Structure

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).

Structure JSON Representation (extract)

{
  "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"
    }
    ...
  }
}

Navigating to a Workflow Instance¶

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.

Retrieve Workflow Instance List

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

Retrieve Single Workflow Instance

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)

Single Workflow instance JSON Representation

{
  "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.

Specifying Locale in Request

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