Care Plans

A CarePlan is a patient's active treatment or monitoring plan. It instantiates a PlanDefinition, the governed, versioned protocol that describes the actions to perform. Palamond separates the two clearly: the PlanDefinition is the catalog template (shared, governed), and the CarePlan is the patient's instance. You read plans from the record plane; the enrollment endpoints own the lifecycle.

The shape

The plan always pins the exact protocol version it instantiated. A version published later does not retroactively change an active plan.

The catalog

PlanDefinition resources are authored and deployed centrally as versioned canonicals. Your app does not resolve them itself: protocols.list lists what the organization offers, and entries with a protocol canonical are enrollable.

const catalog = await palamond.protocols.list();
const enrollable = catalog.filter((p) => p.protocol);
// [{ healthcareService: 'HealthcareService/...', name: '...', protocol: 'https://...|1.0.0' }]

Enrollment is draft, then activate

Enrollment is a two-step lifecycle so a plan can be prepared before it starts driving work:

1. Enroll (enrollments.create) creates a draft CarePlan from the catalog entry. Nothing is scheduled yet.
2. Activate (enrollments.activate) flips it to active, sets period.start, and generates the plan's actions: immediate tasks, scheduled appointments, and recurring occurrences.

const { carePlan } = await palamond.enrollments.create({
  healthcareService: enrollable[0].healthcareService,
});
// carePlan.status === 'draft'

const activated = await palamond.enrollments.activate(carePlan.id);
// activated.carePlan.status === 'active'

The platform resolves the protocol behind the catalog entry server-side, so patients never need to read a PlanDefinition.

The full flow is in Enroll in a Care Plan.

Provider-proposed plans

A plan can also originate from the care team. When a provider selects a treatment and composes it, the platform stands up a draft CarePlan immediately, so the proposed plan is visible on the chart before the patient has decided. To the patient, this surfaces as a proposed plan they can accept or decline.

Show proposed plans by querying draft plans (searches are auto-scoped to the signed-in patient):

const proposed = await palamond.searchResources('CarePlan', { status: 'draft' });

Accepting is activation: enrollments.activate flips the draft to active and instantiates exactly the version the patient was shown. Declining is enrollments.end, which revokes the draft and cancels its open work.

Reading a patient's plans

const plans = await palamond.searchResources('CarePlan', {
  'status:not': 'revoked',
});

Group by status to separate active plans from proposed ones, and read title and instantiatesCanonical to label them.