Encounters and Tasks

Two resources carry the operational work of a visit: the Encounter (one unit of clinical contact) and the Task (a unit of work to do). Palamond models both with a distinctive rule: an appointment is made of one or more encounters, and a task completion is the action that advances the workflow. Understanding those two ideas is most of what you need to build against them.

An appointment is made of visit segments

The Appointment is the scheduled commitment: when the visit is, and whether it still stands. Each Encounter beneath it is one visit segment: a single unit of contact, with its own purpose, care team, format, and status lifecycle.

Appointment          the scheduled commitment
  └ Encounter[]        one segment per contact
       └ Task[]          the work inside that contact

Most visits have exactly one segment. The model earns its keep when a visit does not: a patient who fills in a form, then meets one team, then meets a second team is three segments under one booking, each routed to its own owner and each with its own join link.

Segments are created planned when the appointment is booked, so there is always a record to attach work and metadata to. A planned segment is an intention, not a clinical event: it is not a visit that happened, and it should not be rendered as one.

Read an appointment's segments in declared order:

const segments = await palamond.appointments.segments(appointmentId);

for (const { segment, purpose, status } of segments) {
  console.log(segment, purpose, status);
}

Each entry carries the segment id to pass to startEncounter, its purpose and status, its 0-based sequence, and the full encounter. Cancelled segments are left out. The underlying Encounters are readable from the record plane too (Encounter?appointment=Appointment/{id}), but the ordering and the segment ids are decoded for you here.

Starting a segment

A segment begins when someone actually shows up. That is a status transition, not a create:

const { encounter, created, reopened } = await palamond.appointments.startEncounter(appointmentId);

The call is idempotent, so a double-click or a retry never advances anything twice. Without a segment named explicitly it starts the next one that has not finished, which for a single-segment visit is always the only one. reopened tells you a released segment was resumed rather than a new one spawned. A 409 consent_required means required agreements are unmet; accept them via the agreements endpoints and retry (see Errors and Limits).

created is normally false, because the segment already existed from booking. It is true only when the platform had to heal an appointment booked before visit segments existed.

Segment fields

Three fields between them say what kind of contact this is, because no one of them can. The modality coding answers store-and-forward; class answers in-person; and the call medium separates a video consult from a phone call, which are both VR and both sync. Read all three, or read the segment's format from whichever of them applies:

Purpose is a further axis, independent of all of them. class says where a contact happens, the modality coding says whether it is real time, and purpose says what it is for:

When each segment happens

One appointment is one commitment in time, and its segments divide that commitment up in one of two ways.

Live segments run back to back inside the booked window. A visit booked at 09:00 whose first contact is 10 minutes and second is 20 puts the nurse at 09:00 and the doctor at 09:10, and the appointment runs to 09:30. Each segment carries its own period, so the times are on the record rather than implied.

Because each segment can be routed to a different team, the window has to work for all of them: a time is only offered when the nurse is free for 09:00–09:10 and a doctor is free for 09:10–09:30. Availability is solved across the segments in order rather than against one team's calendar for the summed length, and each segment is assigned the provider found for its own stretch. Booking re-validates the same way, so a segment whose provider has since been taken is rejected rather than double-booked.

Asynchronous segments occupy no slot, so they can sit before or after the visit. Their timing is declared as a whole number of days relative to the appointment start, and it is materialized onto every step Task in that segment as restriction.period:

restriction.period.start is when the patient may begin, and starting earlier is refused. restriction.period.end is when it is due, and it is a soft deadline: it drives readiness ("2 of 3 done") so a care team can see whether the patient did their part, and it never blocks the visit from going ahead.

Because the offset is stored relative to the appointment rather than as a date, rescheduling carries the whole window with it: move the visit a week later and the prepare-ahead work opens a week later too.

The work a segment generates

Every segment carries exactly one care-team Task, and which one follows from its modality rather than from anything the booker declared:

The rule is the platform's, not the caller's: a visit booked with no steps and no declared review still produces the work someone owes. A segment that asks the patient for nothing has nothing to wait on, so its review opens immediately.

Because the task belongs to the segment, a visit that meets one team and then another puts one task in each queue, and an in-person visit generates one just as a video visit does. Cancelling a segment retires its outstanding task; a task already claimed is never rewritten.

Neither task is patient-facing, so neither appears in a patient session.

Tasks: the patient's to-do list

A Task is one piece of work inside a segment. The API exposes the patient's own tasks: complete a questionnaire, capture a measurement, decide an order. Clinician work (chart reviews, request reviews) is routed through care-team queues by the platform and is never visible to a patient session.

Every step task carries Task.encounter pointing at the segment it belongs to, and Task.basedOn including the appointment, so you can read a visit's work either way.

const tasks = await palamond.searchResources('Task', {
  status: 'requested,in-progress',
});

const steps = await palamond.searchResources('Task', {
  encounter: `Encounter/${segmentId}`,
});

Read Task.status and Task.description to render the list, and let the SDK's getTaskKind tell you what each task is ('questionnaire' | 'measurements' | 'medication' | 'order'), so the right screen renders without inspecting the task's internals. getRequestedMeasurements and getMedicationOptions read the typed inputs the same way. Complete an Assessment walks through all four kinds.

Completing a task

tasks.complete is the one action. It takes the task (a bare id or a Task/<id> reference) and the work product, exactly one of questionnaireResponse, measurements, medicationRequest, or decline: true:

await palamond.tasks.complete(task.id, {
  questionnaireResponse: `QuestionnaireResponse/${response.id}`,
});

await palamond.tasks.complete(task.id, {
  measurements: [{ loinc: '29463-7', value: 72, unit: 'kg', code: 'kg' }],
});

A medication suggestion task completes with medicationRequest (the proposal recorded first via requests.create), or with decline: true when the patient wants none of the suggestions.

Every shape accepts an optional encounter to link the work to a segment. Completion is what moves the workflow: the platform stores the results, closes the task, and opens whatever comes next (for example the clinician review once an intake is done). It returns the completed Task.

One task kind has its own action: a task whose focus is an order proposal is completed by recording the decisions with orders.decide (see Orders).

Timing on restriction.period

Task.restriction.period carries two independent time semantics:

• period.start is a not-before gate. A task scheduled for the future is not yet actionable; completing it early answers 409 with details.notBefore. Hide or disable such tasks until their start.
• period.end is the deadline. A future deadline never blocks completion; it only marks the task overdue once it passes. Use it to sort and badge the to-do list.

A task that is already closed also answers 409 conflict, so a retried completion can never run twice. See Errors and Limits for the envelope.

What a patient app reads

A patient app works almost entirely from tasks, appointments, and segments:

• upcoming and past visits from Appointment, plus its segments for what each contact is,
• to-dos from Task (intake questionnaires, measurement capture, order decisions),
• the resource each task points at via Task.focus, to render the right screen.

Filter planned segments out of anything that reads as visit history: until a segment starts, nothing has happened yet.

Complete tasks through POST /v1/tasks/{id}/complete and the platform moves the workflow forward.