# OHH Retrieve CarePlan - Open Health Hub FHIR Implementation Guide v0.1.0

* [**Table of Contents**](toc.md)
* [**Artifacts Summary**](artifacts.md)
* **OHH Retrieve CarePlan**

## Resource Profile: OHH Retrieve CarePlan 

| | |
| :--- | :--- |
| *Official URL*:https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-retrieve-care-plan | *Version*:0.1.0 |
| Active as of 2025-12-03 | *Computable Name*:OhhRetrieveCarePlan |

 
A profile on the CarePlan resource describing the information returned by the GET operation. 

### Scope and Usage 

A CarePlan contains the task for the patient and/or caregivers for a specific PlanDefinition. The tasks will reference the Open Health Hub Form Filler to easily fill out forms.

**Usages:**

* Examples for this Profile: [CarePlan/4](CarePlan-4.md)
* CapabilityStatements using this Profile: [OHH FHIR API](CapabilityStatement-ohh-capability-statement.md)

You can also check for [usages in the FHIR IG Statistics](https://packages2.fhir.org/xig/ohh-fhir|current/StructureDefinition/ohh-retrieve-care-plan)

### Formal Views of Profile Content

 [Description of Profiles, Differentials, Snapshots and how the different presentations work](http://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#structure-definitions). 

 

Other representations of profile: [CSV](StructureDefinition-ohh-retrieve-care-plan.csv), [Excel](StructureDefinition-ohh-retrieve-care-plan.xlsx), [Schematron](StructureDefinition-ohh-retrieve-care-plan.sch) 

### Notes:

### Retrieving a CarePlan

A CarePlan can be retrieved by its ID using a GET request. Alongside standard FHIR fields, the CarePlan will contain the following customised fields:

* An extension containing the URL the patient needs to open the program (program-link)
* An extension containing the PIN which the patient needs to register the program (program-pin)
* Two extensions that contain the Customized Invite Mail text and image when set in the Improve Designer (custom-invite-image and custom-invite-text)
* An extension with a link to the embedded form filler program timeline. This will only be present when the patient is already registered to the program (form-filler-program-timeline).
* Two careTeam references. Both CareTeams contain a list of Practitioner references: 
* In the CareTeam with the same id as the CarePlan, Practitioners have a public key that should be used for encrypting the QuestionnaireResponses that fulfill activities in this CarePlan.
* The CareTeam where the id has a `-caregivers` suffix lists the Practitioners that have activities in this CarePlan. They are referenced by their role.
 
* An activity list. Every activity represents either a questionnaire for the patient or a caregiver of the patient, or a communication request to remind the patient to fill in the questionnaire (push notification or a call from the responsible health care professional). Questionnaires are calculated dynamically based on input from previous questionnaires, so the list is not final and can grow over time. The questionnaire activities contain two extensions to open the specific questionnaire directly in the embedded form filler (form-filler-program-task, task-uuid).

#### Using with the Embedded Form Filler

Besides using the embedded form filler links in the extensions, you can also build the links to the embedded form filler yourself:

URL format: https://formfiller.openhealthhub.com/user/<user-uuid>/program/<program-uuid>-<invite-id>/module/<task-uuid>?signature=<signature>&key=<key>

Values are retrieved from the following CarePlan fields:

* user-uuid (Patient): contained subject.identifier with system urn:ietf:rfc:3986, without the urn:uuid: prefix
* user-uuid (Practitioner): activity.detail.performer.reference (the id of the referenced Practitioner)
* program-uuid: instantiatesCanonical (only the UUID part after PlanDefinition)
* invite-id: id
* task-uuid: activity.detail.extension (value of task_uuid extension) — optional when you want to open a specific questionnaire directly
* signature: contained subject.extension with url https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/patient-signature
* key: must be appended by integrator; obtained from the Open Health Hub administration page and identifies your organisation

When using the embedded form filler links you will need to append the `key` query parameter yourself. This key can be obtained from our administration page by your organisation admin. The key identifies your organisation and determines the method of authentication for the patient.



## Resource Content

```json
{
  "resourceType" : "StructureDefinition",
  "id" : "ohh-retrieve-care-plan",
  "url" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-retrieve-care-plan",
  "version" : "0.1.0",
  "name" : "OhhRetrieveCarePlan",
  "title" : "OHH Retrieve Care Plan Profile",
  "status" : "active",
  "date" : "2025-12-03T12:00:57+00:00",
  "publisher" : "Open Health Hub",
  "contact" : [
    {
      "name" : "Open Health Hub",
      "telecom" : [
        {
          "system" : "url",
          "value" : "https://www.openhealthhub.com"
        },
        {
          "system" : "email",
          "value" : "support@openhealthhub.com"
        }
      ]
    }
  ],
  "description" : "A profile on the CarePlan resource describing the information returned by the GET operation.",
  "fhirVersion" : "4.0.1",
  "mapping" : [
    {
      "identity" : "workflow",
      "uri" : "http://hl7.org/fhir/workflow",
      "name" : "Workflow Pattern"
    },
    {
      "identity" : "rim",
      "uri" : "http://hl7.org/v3",
      "name" : "RIM Mapping"
    },
    {
      "identity" : "w5",
      "uri" : "http://hl7.org/fhir/fivews",
      "name" : "FiveWs Pattern Mapping"
    },
    {
      "identity" : "v2",
      "uri" : "http://hl7.org/v2",
      "name" : "HL7 v2 Mapping"
    }
  ],
  "kind" : "resource",
  "abstract" : false,
  "type" : "CarePlan",
  "baseDefinition" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-base-care-plan",
  "derivation" : "constraint",
  "differential" : {
    "element" : [
      {
        "id" : "CarePlan",
        "path" : "CarePlan",
        "constraint" : [
          {
            "key" : "care-providers-requirement",
            "severity" : "error",
            "human" : "Exactly 1 care providers CareTeam",
            "expression" : "careTeam.where(reference.exists() and reference.matches('^CareTeam/[0-9]+$')).count() = 1",
            "source" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-retrieve-care-plan"
          },
          {
            "key" : "caregivers-requirement",
            "severity" : "error",
            "human" : "At most 1 caregivers CareTeam",
            "expression" : "careTeam.where(reference.exists() and reference.matches('CareTeam/[0-9]+-caregivers$')).count() <= 1",
            "source" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-retrieve-care-plan"
          }
        ]
      },
      {
        "id" : "CarePlan.extension",
        "path" : "CarePlan.extension",
        "slicing" : {
          "discriminator" : [
            {
              "type" : "value",
              "path" : "url"
            }
          ],
          "rules" : "closed"
        }
      },
      {
        "id" : "CarePlan.extension:programLink",
        "path" : "CarePlan.extension",
        "sliceName" : "programLink",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/program-link"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.extension:programPin",
        "path" : "CarePlan.extension",
        "sliceName" : "programPin",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/program-pin"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.extension:customInviteImage",
        "path" : "CarePlan.extension",
        "sliceName" : "customInviteImage",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/custom-invite-image"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.extension:customInviteText",
        "path" : "CarePlan.extension",
        "sliceName" : "customInviteText",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/custom-invite-text"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.extension:formFillerProgramTimeline",
        "path" : "CarePlan.extension",
        "sliceName" : "formFillerProgramTimeline",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/form-filler-program-timeline"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.status",
        "path" : "CarePlan.status",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.subject.reference",
        "path" : "CarePlan.subject.reference",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.period.end",
        "path" : "CarePlan.period.end",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.careTeam",
        "path" : "CarePlan.careTeam",
        "min" : 1,
        "max" : "2"
      },
      {
        "id" : "CarePlan.activity",
        "path" : "CarePlan.activity",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.outcomeReference",
        "path" : "CarePlan.activity.outcomeReference",
        "max" : "1",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail",
        "path" : "CarePlan.activity.detail",
        "min" : 1,
        "constraint" : [
          {
            "key" : "valid-activity-detail-code",
            "severity" : "error",
            "human" : "Activity detail code must be from questionnaire-types or action-type code systems",
            "expression" : "code.coding.where(system.endsWith('/questionnaire-types') or system.endsWith('/action-type')).exists()",
            "source" : "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/ohh-retrieve-care-plan"
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.extension",
        "path" : "CarePlan.activity.detail.extension",
        "slicing" : {
          "discriminator" : [
            {
              "type" : "value",
              "path" : "url"
            }
          ],
          "rules" : "closed"
        }
      },
      {
        "id" : "CarePlan.activity.detail.extension:formFillerProgramTask",
        "path" : "CarePlan.activity.detail.extension",
        "sliceName" : "formFillerProgramTask",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/form-filler-program-task"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.extension:taskUuid",
        "path" : "CarePlan.activity.detail.extension",
        "sliceName" : "taskUuid",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/task-uuid"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.extension:relatedQuestionnaire",
        "path" : "CarePlan.activity.detail.extension",
        "sliceName" : "relatedQuestionnaire",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Extension",
            "profile" : [
              "https://api.openhealthhub.com/OpenHealthhub/fhir/4/StructureDefinition/related-questionnaire"
            ]
          }
        ],
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.instantiatesCanonical",
        "path" : "CarePlan.activity.detail.instantiatesCanonical",
        "max" : "1",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.code",
        "path" : "CarePlan.activity.detail.code",
        "min" : 1
      },
      {
        "id" : "CarePlan.activity.detail.status",
        "path" : "CarePlan.activity.detail.status",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.scheduled[x]",
        "path" : "CarePlan.activity.detail.scheduled[x]",
        "slicing" : {
          "discriminator" : [
            {
              "type" : "type",
              "path" : "$this"
            }
          ],
          "ordered" : false,
          "rules" : "open"
        }
      },
      {
        "id" : "CarePlan.activity.detail.scheduled[x]:scheduledPeriod",
        "path" : "CarePlan.activity.detail.scheduled[x]",
        "sliceName" : "scheduledPeriod",
        "min" : 0,
        "max" : "1",
        "type" : [
          {
            "code" : "Period"
          }
        ]
      },
      {
        "id" : "CarePlan.activity.detail.scheduled[x]:scheduledPeriod.start",
        "path" : "CarePlan.activity.detail.scheduled[x].start",
        "min" : 1,
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.scheduled[x]:scheduledPeriod.end",
        "path" : "CarePlan.activity.detail.scheduled[x].end",
        "min" : 1,
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.performer",
        "path" : "CarePlan.activity.detail.performer",
        "mustSupport" : true
      },
      {
        "id" : "CarePlan.activity.detail.description",
        "path" : "CarePlan.activity.detail.description",
        "mustSupport" : true
      }
    ]
  }
}

```
