> For the complete documentation index, see [llms.txt](https://docs.qvantum-plan.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qvantum-plan.de/dev/team.md).

# Define Team

With all prior preparations done, it now makes sense to define a team of planning users.

{% hint style="info" %}
A plan can only be started once a planning team has been defined for it: at least one planner with write permission (`input` allowed) must exist.
{% endhint %}

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 plan with respective permissions. Technically, these steps are realized with different API endpoints for user management and assignment to plans.

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

{% hint style="info" %}
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.
{% endhint %}

**Sample User Definition**

```csv
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.                                                                                         |

{% hint style="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.
{% endhint %}

{% hint style="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.
{% endhint %}

#### 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](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) 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**

```sh
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_UPLOADS_LINK}"
```

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](/dev/model.md#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.

{% hint style="warning" %}
Retrieved user definitions including controller users cannot be uploaded again, as these users are created with a different workflow.
{% endhint %}

**Retrieve User Definition (planners only)**

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

The same resource also serves a JSON representation of the users, which in contrast to the CSV export includes the roles of each user and a link per user. As CSV is the default, the JSON representation has to be requested explicitly with an accept header:

**Retrieve User Definition as JSON**

```sh
curl --silent --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  --header "Accept:application/hal+json" \
  "${TENANT_USERS_LINK}"
```

### Retrieve a Single User

Following the `self` link of a user, or the `user` link of a planner status (cf. [planner status](/dev/update_workflow.md#planner-status)), leads to a single user.

**Retrieve a Single User**

```sh
curl --silent --request GET \
  --header "Authorization:Bearer ${TOKEN}" \
  "${USER_LINK}"
```

**User JSON Representation**

```json
{
  "emailAddress": "planner@example.com",
  "firstName": "Decentral",
  "lastName": "Planner",
  "singleSignOnUserId": null,
  "roles": [ "DECENTRAL_PLANNER" ],
  "_links": {
    "self": {
      "href": "https://api.qvantum-plan.de/api/v1/users/2"
    },
    "owner": {
      "href": "https://api.qvantum-plan.de/api/v1/tenants/1"
    }
  }
}
```

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

{% hint style="info" %}
For the same permission model explained from the QVANTUM Web application's Team tab, with screenshots, see the German user documentation: [Planungsteam verwalten](/user/owner/planung/team/nutzer-berechtigungen_in_qvantum_definieren.md) (German)
{% endhint %}

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**

```csv
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 plan, 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](https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8) 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**

```sh
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}" \
  "${ALL_PERMISSIONS_LINK}"
```

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**

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