Completing Task Occurrences

A task template defines what has to be done and how often; each day the schedule lands on is an occurrence. The calendar endpoint lists an outlet's occurrences and is where the opaque occurrence_id comes from. Everything below is done through Save Task Occurrence.

Planned, draft, completed

A planned occurrence has no record of its own. The schedule says it should happen, and nothing has been written yet. The first save creates that record, which is why one request both starts a draft and completes it, depending on completed.

Completion is one-way. completed: true stamps the occurrence as done; a completed occurrence cannot be sent back to draft with completed: false. Later edits are kept as versions: each one writes a new version and moves the previous into history.

Permissions

Saving requires permission to perform the task in the occurrence's outlet. Editing an occurrence that is already completed additionally requires the permission to edit completed tasks. Without it, only remarks and custom_fields are accepted and a payload touching any other field answers 403, so the recorded values (temperatures, checklist, done_by) stay as they were completed.

Who performed the task

done_by records who carried the task out and comes back as completion.done_by. It has to be a user of the library with access to the occurrence's outlet, and it is not defaulted: left out, it stays as it was. The requesting user is recorded separately, as completion.submitted_by.

Entering values

type_specific accepts only the key of the occurrence's own task type. See Template types for which key that is. Temperature measurements are matched to the template's ranges by key, and value has to be a number; a numeric string is rejected. checklist carries the labels of the checked items, and a label the template does not define is rejected.

The entered values also decide the outcome: an occurrence whose values fall outside the template's ranges, or whose checklist is not fully checked, completes with completion.result nok.

The two keys merge by opposite rules

This is the part worth reading twice, because it decides what a partial update does:

So ticking one more checklist item means sending that label together with every label that was already ticked. Sending only the new one unchecks the rest. Checklist items are plain labels with no id of their own, which is why they cannot be addressed one at a time the way a temperature key can.

Custom fields and corrective actions

custom_fields is keyed by field slug, as returned by Get Task Custom Fields. A slug the library does not define is rejected, a choices field takes one of its configured options and a multi field a list of them.

mitigation_skipped is only accepted when the occurrence's mitigation_policy is 1 (optional). With any other policy, skipping the corrective action is not a choice the caller has.

What completion demands

Completing an occurrence answers 400 while any of the following holds:

• a value of its task type is still missing
• a required custom field is not filled in
• the result is nok and remarks is empty
• the occurrence is ahead of its scheduled day while the template has prevent_early_execution set

Attachments are never touched by the save endpoint. The ones already on the occurrence are kept.