Define Team¶

With all prior preparations done, it now makes sense to define a team of planning users. This definition of a team takes place in two steps. First, all users must exist in the context of a tenant. Non-existing users must be created, providing their user information. Second, users must be assigned to a planning application with respective permissions. Technically, these steps are realized with different API endpoints for user management and assignment to planning applications.

Warning

The separation of defining a team in two steps replaces the prior approach to define user information and permission assignments in one step. Old API endpoints were removed in favor of the new endpoints described below. This breaking API change effectively requires all API users to adapt their client applications accordingly.

Manage Users¶

Users in a team are managed via user definition CSV files. A user definition CSV file includes the following fields:

last-name: Last name of planning user
first-name: first name of planning user
email: email address of planning user
single-sign-on-user-id: unique user id for Single Sign On

This definition implicitly differentiates two types of possible users in QVANTUM:

QVANTUM-managed: define first name, last name and email, omit single sign on user id.
Single Sign On (SSO): define all fields, email and single sign on user id must refer to the same user.

Important

SSO must be actively configured for a tenant by the QVANTUM team in collaboration with the IT administration team in control of this tenant. The definition of SSO users is possible at all times. However, login for users with an SSO user definition will only be possible after successful SSO configuration for the respective tenant.

Sample User Definition

last-name;first-name;email
Checker;Chris;chris@example.com
Seller;Sally;sally@example.com
Adminsky;Adam;adam@example.com

Upload User Definition¶

A valid user definition file is uploaded to QVANTUM in one single asynchronous API call with its result enabling status polling afterwards. The upload of users follows synchronization semantics, i.e. the current tenant in QVANTUM is synchronized with the users in the uploaded team file, according to the following synchronization rules:

User in QVANTUM	User in CSV	Synchronization Operation
no	no	-
no	managed	User is created in tenant and an invitation email with the initial password is send.
no	SSO	User is created in tenant and an invitation email without an initial password is send.
managed	no	User is removed from tenant.
managed	managed	User information is updated.
managed	SSO	User information is updated and login via password is disabled.
SSO	no	User is removed from tenant.
SSO	managed	User information is updated and an invitation email with an initial password is send. Login via SSO no longer works.
SSO	SSO	User information is updated.

Warning

This effectively means that updating a team requires to upload a complete updated user definition file with all wanted planning users under a tenant, including the ones that existed before.

Warning

Users are only matched via their email address. If the email for a user changed, the old user account will be deleted and a new account will be created with the new email address.

Asynchronous Upload¶

Technically, the upload of a user definition file is a request with the user CSV file as the body. One additional parameter in the MIME type allows to further specify the format of the uploaded file:

charset: the charset to be used. Valid values are US-ASCII, ISO-8859-1, UTF-8, UTF-16, UTF-16BE, UTF-16LE, and Windows-1252. If omitted, defaults to UTF-8. As for files encoded in UTF-8, any optionally included BOM is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail.

Upload User Definition

USER_DEFINITION_PATH="/path/to/user/definition/users.csv"

curl --show-headers --request POST \
  --header "Authorization:Bearer ${TOKEN}" \
  --header "Content-Type:text/csv" \
  --data-binary "@${USER_DEFINITION_PATH}" \
  "${TENANT_USER_UPLOAD_URL}"

Uploading user definitions with one of the above requests is asynchronous, i.e. the QVANTUM Public API will immediately send a response including a status polling URL in the Location header. In the next step, repeated status polling allows to monitor the status of user definition processing on QVANTUM side. The returned URL leads to an upload history entry resource ${HISTORY_ENTRY_URL}. Status polling works as described for the model upload (cf. Upload Status Polling). The only difference is the missing cubeKey field in the history entry.

Retrieve User Definition¶

User definition is retrieved with a simple GET request, serving user definition CSV content in its response body. An optional boolean request parameter includeControllers allows to control whether the retrieved user definition includes controller and planning users (default) or planning users only.

Warning

Retrieved user definitions including controller users cannot be uploaded again, as these users are created with a different workflow.

Retrieve User Definition (planners only)

curl --silent --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  "${TENANT_USERS_URL}?includeControllers=false"

Important

A full interaction path with the QVANTUM public API regarding user definition upload and retrieval is demonstrated in the script qvantum-user-definition.sh in our sample data set.

Assign Permissions¶

In general, each planner must be explicitly granted sufficient permissions to view or even enter planning data, according to his planning responsibilities. In QVANTUM, a permission assignment is defined as a list of references to planning users including their respective permissions across dimensions. This list is then encoded in a permission assignment CSV file for later upload via the QVANTUM Public API.

A permission assignment CSV file includes the following fields:

email: email address of planning user
The plural labels of the dimensions used to define permissions
input: input allowed for planning user

Permissions in keyfigure and time dimensions are not allowed.

There are three possible ways to define permissions in a dimension: * : an empty value means that the planner has no permission in the dimension * [a] [b]: a list of element keys. The planner has permissions on those elements and their descendants * all: the planner has permissions on all elements in the dimension

Sample Permission Assignment File

email;Cost Centers;Scenarios;input
chris@example.com;[CCT000];[PLAN];no
sally@example.com;[CCT000][CCT010];[FORECAST];yes
adam@example.com;all;all;yes

The above example of a permission assignment CSV file defines the permissions for three planning users:

Sally is responsible for contributing forecast figures for the sales cost center.
Adam is responsible for contributing plan figures for the sales and administration cost centers.
Chris is responsible for checking all figure contributions across all cost centers.

Upload Permission Assignment¶

A valid permission assignment file is uploaded to QVANTUM in one single synchronous API call. The upload of a permission assignment follows upsert semantics, i.e. user permissions are either defined or updated.

Synchronous Upload¶

Technically, the upload of a permission assignment is a PUT request in the context of a planning application, with contents of a permission assignment CSV file in the body. One additional parameter allows to further specify the format of the uploaded permission assignment file:

charset: the charset to be used. Valid values are US-ASCII, ISO-8859-1, UTF-8, UTF-16, UTF-16BE, UTF-16LE, and Windows-1252. If omitted, defaults to UTF-8. As for files encoded in UTF-8, any optionally included BOM is safely ignored. If any explicit or implicit charset specification does not match the actual charset of the corresponding file, the upload will fail.

Upload Permission Assignment

PERMISSION_ASSIGNMENT_PATH="/path/to/permission/assignment/permissions.csv"
curl --show-headers --request PUT \
  --header "Authorization:Bearer ${TOKEN}" \
  --header "Content-Type:text/csv" \
  --data-binary "@${PERMISSION_ASSIGNMENT_PATH}" \
  "${PLANNING_APPLICATION_ALL_PERMISSIONS_URL}"

Uploading permission assignment with one of the above requests is synchronous. The operation either succeeds with a response with HTTP status 204 or a status 422 including an error message in the body.

Retrieve Permission Assignment¶

Permission assignments are retrieved with a simple GET request, serving permission assignment CSV content in its response body.

Retrieve Permission Assignment

curl --silent --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  --header "Content-Type:text/csv" \
  "${PLANNING_APPLICATION_ALL_PERMISSIONS_URL}"

Important

A full interaction path with the QVANTUM public API regarding permission assignment upload and retrieval is demonstrated in the script qvantum-permission-assignment.sh in our sample data set.