Recording Task Occurrences

There is a full API collection for recording compliance tasks. A task template defines what has to be done and how often, and each day its schedule lands on is an occurrence. Every endpoint on this page acts on one occurrence, addressed by the opaque occurrence_id that the calendar endpoint returns.

Occurrence states

An occurrence starts out uncompleted: the schedule says it should happen, and no result has been recorded yet. Values can be saved on it in the meantime, and it stays uncompleted until it is resolved.

From there, an occurrence becomes resolved in one of two ways. It is completed, with the values the task asks for, or it is marked not applicable, because the check could not be performed at all. Either way it leaves the "still to do" list, but only a completion produces a pass or fail outcome.

Each state shows in completion.result:

Resolving is one-way. No call takes a resolved occurrence back to uncompleted, and every later edit is kept as a version, with the previous one moved into history.

Step by step instructions

These steps should be followed in this order to record a task occurrence via the Apicbase API:

1. Get the outlet's tasks calendar and take the occurrence_id of the occurrence you want to record.
2. Optionally, save values on the occurrence as they are entered. It stays uncompleted.
3. Optionally, attach a file, for example the photo backing up a check.
4. Resolve the occurrence: complete it with the values the task asks for, or mark it not applicable if the check could not be performed.

The occurrence is only resolved at step 4. Save, complete and mark not applicable take the same payload, except that only complete accepts mitigation_skipped, and all three answer with the full occurrence. The value sets they use are listed on the Reference Values page.

Get Task Occurrence Details reads one occurrence at any point, with its template, the values entered, the completion state and the history. Delete Task Occurrence Attachment detaches a file but keeps the file itself. Delete Task Occurrence drops the occurrence and excludes its day from the schedule.

Editing a resolved occurrence

Once an occurrence is resolved, each part of it has one endpoint that edits it:

• The values it was resolved with are edited through complete, which recalculates completion.result.
• remarks, custom_fields and done_by are edited through save, which refuses type_specific on a resolved occurrence.
• Not applicable is refused outright. An occurrence is declared not applicable once, and the way back is a real completion.

Marking an occurrence not applicable

Marking an occurrence not applicable records that the check could not be performed, for example because the fridge is broken or the delivery never arrived, rather than that it was missed. completion.result becomes not_applicable, and so does the result of any history entry that was itself not applicable.

A not applicable occurrence leaves the denominator of the outlet's completion rate instead of counting against it. With 50 occurrences planned, 3 marked not applicable and 47 completed, the outlet reads as 100% done, with the three reported separately.

If circumstances change on the same day, record the real result with complete directly: the fridge is fixed, the temperature is measured, and the same call records it. There is no step that only clears the not applicable state.

Entering values

Save, complete and mark not applicable all take the occurrence's values in type_specific, under the key for its task type. See Template types for which key that is. Save only accepts them while the occurrence is uncompleted. The values 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.

A request does not have to send every value again, but what happens to the values it leaves out depends on the key:

• temperatures are written one measurement at a time. Only the measurements in the request change, and any measurement left out keeps the value already recorded.
• checklist is replaced as a whole. Any label left out is stored as unchecked, so to tick one more item, send its label together with every label already ticked.

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.

done_by records who carried the task out, such as the cook who took the temperature. completion.submitted_by records the user whose session sent the request. The two differ whenever the performer is picked from a list rather than logged in, which is the normal case on a shared kitchen tablet.