> 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/update_workflow.md).

# Updating a Plan

## Plan Status

Changes on a planning model might require an update of the plan status. During a running plan, no model upload, model update and no structure update are possible. So in this case the status has to be updated.

{% hint style="info" %}
For the same plan lifecycle explained from the QVANTUM Web application's Übersicht tab, with screenshots, see the German user documentation: [Der Workflow](/user/owner/planung/ubersicht/der_workflow.md) (German)
{% endhint %}

{% hint style="warning" %}
There are some restrictions when changing the 'status' of the plan:
{% endhint %}

Only the following transitions are allowed:

| current status | new status   |
| -------------- | ------------ |
| NOT\_STARTED   | RUNNING      |
| RUNNING        | PAUSED       |
| PAUSED         | RUNNING      |
| RUNNING        | FINISHED     |
| FINISHED       | NOT\_STARTED |
| FINISHED       | EXPORTED     |
| EXPORTED       | NOT\_STARTED |

The change of the status to 'RUNNING' is only allowed when

* a planning model is present
* at least one editor is present
* at least one form exists in the plan

It is also possible to change the title or the end date of the plan.

The update of a plan can be performed with a PATCH-request:

```sh
curl --silent --show-headers --request PATCH \
  --header "Authorization:Bearer ${TOKEN}" \
  --header "Content-Type:application/json-patch+json" \
  --data JSON_PATCH \
  "${PLAN_LINK}"
```

JSON\_PATCH is a place holder for the following use cases:

* changing the title:

```json
[
  {
    "op": "replace",
    "path": "/title",
    "value": "new Title"
  }
]
```

* changing the end date:

```json
[
  {
    "op": "replace",
    "path": "/endDate",
    "value": "new end date"
  }
]
```

* changing the status:

```json
[
  {
    "op": "replace",
    "path": "/status",
    "value": "updated status"
  }
]
```

To pause a plan you have to set the status of a running plan to "PAUSED". To resume then to a running plan you have to set the status to "RUNNING".

* You can update more than one field within one request:

```json
[
  {
    "op": "replace",
    "path": "/title",
    "value": "new Title"
  },
  {
    "op": "replace",
    "path": "/status",
    "value": "RUNNING"
  }
]
```

## Planner Status

Besides the status of the plan as a whole, every planner of a plan has an own status, describing how far that planner has come in the planning process.

{% hint style="info" %}
For the same planner status values explained from the planner's and the owner's perspective in the QVANTUM Web application, see the German user documentation: [Der Workflow](/user/owner/planung/ubersicht/der_workflow.md#planungsstatus) (German)
{% endhint %}

A planner status resource has the following fields:

* `status`: the planning status of the planner, see the values below
* `submissionDate`: the point in time at which the planner submitted, `null` while the planner has not submitted. This field is set by QVANTUM and cannot be changed through the API.
* `sessions`: the currently open sessions of the planner by their id, describing the online status, see [Online Status](#online-status)

The `status` field may have only these values:

* `OPEN`: the planner is still working on the planning.
* `SUBMITTED`: the planner has submitted the planning.
* `FINALISED`: the planning of the planner has been finalised by a controller.

### Retrieve Planner Status

The status of all planners of a plan is embedded in the plan resource, so retrieving the plan is enough to see the status of everyone (cf. [Navigating to a Plan](/dev/general-information.md#navigating-to-a-plan)).

The status of a single planner is retrieved by following one of the `userStates` links of the plan. Its `user` link leads to the planner (cf. [Retrieve a Single User](/dev/team.md#retrieve-a-single-user)).

**Retrieve Planner Status**

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

### Update Planner Status

The status of a single planner is updated with a PATCH request:

**Update Planner Status**

```sh
curl --silent --show-headers --request PATCH \
  --header "Authorization:Bearer ${TOKEN}" \
  --header "Content-Type:application/json-patch+json" \
  --data '[{ "op": "replace", "path": "/status", "value": "OPEN" }]' \
  "${USER_STATE_LINK}"
```

The operation either succeeds with a response with HTTP status 204, or fails with a status 403 if the requested status is not allowed for the current user, or fails with a status 409 if the status of the plan does not allow the change.

{% hint style="warning" %}
A planner may only change their own status, and only while the plan is running. Every other change of a planner status requires a controller.
{% endhint %}

### Online Status

The `sessions` field of a planner status describes when a planner last worked in the QVANTUM web application. Every session of the planner is listed by its id, with the following fields:

* `lastOnline`: the point in time at which QVANTUM has last heard of this session
* `unsavedChanges`: whether the planner has changes in this session that are not saved yet

QVANTUM makes no guarantees as to when sessions are removed for a planner. Clients should use the `lastOnline` timestamp to calculate the online status of a planner by themselves.

{% hint style="warning" %}
The online status cannot be set through the public API.
{% endhint %}