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.

Warning

There are some restrictions when changing the 'status' of the plan:

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:

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:

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

changing the end date:

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

changing the status:
```
[
  {
    "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:

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

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

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

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

Retrieve Planner Status

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

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.

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.

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.

Warning

The online status cannot be set through the public API.