diff --git a/.github/workflows/build-api-spec-html.yml b/.github/workflows/build-api-spec-html.yml index 1069a2f..d8b2ac3 100644 --- a/.github/workflows/build-api-spec-html.yml +++ b/.github/workflows/build-api-spec-html.yml @@ -4,6 +4,8 @@ on: pull_request: branches: - master + paths: + - 'specification/**' workflow_dispatch: jobs: @@ -15,6 +17,10 @@ jobs: - name: Checkout uses: actions/checkout@v4 + - name: Set short SHA + id: short-sha + run: echo "value=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT" + - name: Setup Node.js uses: actions/setup-node@v4 with: @@ -72,8 +78,22 @@ jobs: - name: Upload API docs artifact + id: upload-artifact uses: actions/upload-artifact@v4 with: - name: api-specs-html-docs + name: api-specs-html-docs-${{ steps.short-sha.outputs.value }} path: build/api-docs if-no-files-found: error + + - name: Comment on PR with artifact links + if: github.event_name == 'pull_request' + uses: unsplash/comment-on-pr@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + msg: | + ## API Spec HTML Docs + + Built from commit `${{ steps.short-sha.outputs.value }}` — [view workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) + + **Download HTML API Specs:** [api-specs-html-docs-${{ steps.short-sha.outputs.value }}.zip](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts/${{ steps.upload-artifact.outputs.artifact-id }}) \ No newline at end of file diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index b669ffa..485a6ba 100644 --- a/specification/patient-care-aggregator-api-consumer-api.yaml +++ b/specification/patient-care-aggregator-api-consumer-api.yaml @@ -156,7 +156,7 @@ servers: paths: /aggregator/events: get: - summary: Get patients referrals, bookings, documents, questionnaires and waiting lists + summary: Get patients referrals, bookings, documents, questionnaires, tasks and waiting lists operationId: get-referrals-and-bookings description: The Wayfinder Patient Care Aggregator CarePlan response will return a FHIR [Bundle](https://www.hl7.org/fhir/r4/bundle.html) resource which will contain one [CarePlan](https://www.hl7.org/fhir/r4/careplan.html) resource per Waiting List Entry, one [CarePlan](https://www.hl7.org/fhir/r4/careplan.html) resource containing all Referrals, Appointments, Documents and Questionnaires and one optional [OperationOutcome](https://www.hl7.org/fhir/r4/OperationOutcome.html) resource (based on the UK Core FHIR specification) for use by the NHS App to the following specification. @@ -451,7 +451,7 @@ components: type: string example: Isle of Wight NHS Trust activity: - description: Array of referral, appointments, documents and questionnaires related to the patients care. + description: Array of referral, appointments, documents, tasks and questionnaires related to the patients care. type: array items: anyOf: @@ -459,6 +459,7 @@ components: - $ref: "#/components/schemas/Appointment" - $ref: "#/components/schemas/Document" - $ref: "#/components/schemas/Questionnaire" + - $ref: "#/components/schemas/Task" externalDocs: description: FHIR UK Core CarePlan (R4) Resource Profile url: https://hl7.org/fhir/R4/careplan.html @@ -1196,6 +1197,310 @@ components: description: ODS Organisation name (NHS Trust) type: string example: THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST + Task: + description: A generic task resource representing an action for the patient to complete (e.g. questionnaire, appointment booking invite). Aligns with FHIR R4 Task and Producer spec implementation. + type: object + required: + - detail + properties: + detail: + description: Details of the task. + type: object + required: + - id + - status + - description + - authored + - reasonCode + - reasonReference + properties: + id: + description: Globally unique identifier for the Task. To be persisted over time. + type: string + example: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c + identifier: + description: The ID of the task in your Patient Portal database (system-specific identifier). + type: object + required: + - system + - value + properties: + system: + description: Local (portal) system identifier URI. + type: string + example: "https://my.portal.com/fhir/Task?Id={system|value}" + value: + description: Local (portal) system identifier value. + type: string + example: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c + status: + description: The status of the task as progressed by the patient. + type: string + enum: + - requested + - rejected + - cancelled + - in-progress + - completed + statusReason: + description: Additional detail about the status of a task, for when further clarity is required, such as the reason a patient rejected an invite to book their appointment. + type: string + enum: + - appointment-type-unsuitable + - condition-resolved + - location-unsuitable + - no-reason-given + - no-response-within-booking-window + intent: + description: Hardcoded to 'plan'. Indicates the intent is to perform as a plan/task (See FHIR Task.intent). + type: string + enum: + - plan + description: + description: The patient-friendly, standardised title of the task suitable for display to patients. For questionnaires, this should match the name shown in your interface and follow the structure {Specialty name} {Questionnaire type}. For appointment booking invites, use the description to indicate the action e.g. 'Book your appointment'. The values presented within this field are required for Data Quality Assurance. + type: string + example: Dermatology pre-assessment questionnaire + authored: + description: Date/time when the task was first made available to the patient in UTC format. + type: string + format: date-time + example: '2025-06-20T18:00:00.000Z' + lastModified: + description: Date/time when the task was last modified by the patient in UTC format. For PIFU questionnaires, represents when the patient last requested a follow-up. + type: string + format: date-time + example: '2025-06-23T12:30:00.000Z' + restriction: + description: Constraints on the task, including deadline for task completion. + type: object + properties: + period: + description: The period during which the task should be actioned. + type: object + properties: + start: + description: The effective start date/time when the task became available to the patient in UTC format. + type: string + format: date-time + example: '2025-06-20T18:00:00.000Z' + end: + description: The effective end date/time by which the task should be completed by the patient in UTC format. For appointment booking invites, this is when the invite expires. + type: string + format: date-time + example: '2025-12-20T00:00:00.000Z' + focus: + description: Reference to the Appointment this task relates to (optional). Not required for appointment booking invites where the appointment doesn't exist yet. + type: object + properties: + type: + description: Resource type. + type: string + enum: + - Appointment + reference: + description: Absolute URL to the linked Appointment. + type: string + example: Appointment/caa99978-05ab-4473-8280-e77ebfe797c4 + for: + description: Patient whom the task relates to. + type: object + required: + - type + - identifier + properties: + type: + description: Resource type. + type: string + enum: + - Patient + identifier: + type: object + required: + - system + - value + properties: + system: + description: URI to identifier NHS Numbers. + type: string + enum: + - "https://fhir.nhs.uk/Id/nhs-number" + value: + description: The patient's NHS Number. + type: string + example: "9000000002" + basedOn: + description: Reference to the related CarePlan (Pathway). Optional, used to identify related tasks from the same pathway. + type: array + minItems: 0 + maxItems: 1 + items: + type: object + properties: + type: + description: Resource type. + type: string + enum: + - CarePlan + identifier: + type: object + required: + - system + - value + properties: + system: + description: Identifier system for Care Pathway. + type: string + enum: + - "https://fhir.nhs.uk/Id/PathwayId" + value: + description: Care pathway identifier. + type: string + example: "RBH5644312231" + owner: + description: Organization responsible for the task (the provider organization). + type: object + required: + - type + - identifier + properties: + type: + description: Resource type. + type: string + enum: + - Organization + identifier: + type: object + required: + - system + - value + properties: + system: + description: URI to identifier NHS Trust Organizations. + type: string + enum: + - "https://fhir.nhs.uk/Id/ods-organization-code" + value: + description: NHS Trust Organization (ODS) code. + type: string + example: "RTD" + display: + description: ODS Organisation name (NHS Trust). + type: string + example: "THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST" + reasonCode: + description: Coding for the type of task to be completed (e.g., questionnaire or appointment booking invite). + type: object + required: + - coding + properties: + coding: + description: Array of codings for the type of task. Use system to distinguish between questionnaire types and booking invite types. + type: array + minItems: 1 + maxItems: 1 + items: + type: object + required: + - system + - code + properties: + system: + description: Identifier system for task type. For questionnaires use Extension-Questionnaire-Type, for appointment booking invites use Extension-Task-Type. + type: string + enum: + - "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" + - "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: + description: Task type code. Examples - 'pifu-triage' for PIFU questionnaires, 'appointment-booking-invite' for booking invites. + type: string + example: "pifu-triage" + display: + description: Human-readable display name for the task type. + type: string + example: "PIFU Triage Questionnaire" + text: + description: Human-readable text description of the task type. + type: string + example: "Patient Initiated Follow-Up Questionnaire" + reasonReference: + description: Reference to the Questionnaire or AppointmentBooking this task is requesting be completed. + type: object + required: + - type + - reference + properties: + type: + description: Resource type being referenced. + type: string + enum: + - Questionnaire + - AppointmentBooking + reference: + description: Absolute URL to the Questionnaire or AppointmentBooking resource in the Portal system. + type: string + example: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c" + extension: + description: FHIR extensions for task resources. Includes Portal link, client ID, optional linked appointment, and treatment function. + type: array + items: + anyOf: + - description: URL for a patient-facing web application for the task. Always present. + type: object + required: + - url + - valueUrl + properties: + url: + description: FHIR extension type. + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: + description: The Portal provider deep link URL to access the task. + type: string + example: "https://my.portal.com/Task/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c" + - description: Unique identifier for the upstream application (Portal) the task came from. + type: object + required: + - url + - valueCode + properties: + url: + description: FHIR extension type. + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: + description: Portal system identifier. + type: string + example: "myportal-01" + - description: Treatment function associated to the Task. Must be provided for PIFU questionnaires. + type: object + properties: + url: + description: Extension URL for treatment function. + type: string + enum: + - "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction" + valueCoding: + type: object + required: + - system + - code + properties: + system: + description: Coding system for treatment function. + type: string + enum: + - "https://fhir.nhs.uk/CodeSystem/Specialty-1" + code: + description: Treatment function code. + type: string + example: "330" + display: + description: Treatment function display name. + type: string + example: "Dermatology" OperationOutcome: description: A FHIR `OperationOutcome` resource containing details of the issues that have occurred. type: object @@ -1394,8 +1699,10 @@ components: $ref: "#/components/examples/allAppointmentStates" allDocumentStates: $ref: "#/components/examples/allDocumentStates" - allQuestionnairestates: - $ref: "#/components/examples/allQuestionnairestates" + allQuestionnaireStates: + $ref: "#/components/examples/allQuestionnaireStates" + allAppointmentBookingInvitationStates: + $ref: "#/components/examples/allAppointmentBookingInvitationStates" incompleteWaitingLists: $ref: "#/components/examples/incompleteWaitingLists" incompleteWaitingListBreastScreening: # Not current supported @@ -1540,7 +1847,7 @@ components: $ref: "#/components/examples/correspondenceReadUnlinked" #Attachment: # $ref: "#/components/examples/Attachment" - # Questionnaires + # Task - Questionnaires questionnaireIncompleteLinked: $ref: "#/components/examples/questionnaireIncompleteLinked" questionnaireIncompleteUnlinked: @@ -1553,6 +1860,21 @@ components: $ref: "#/components/examples/questionnaireCompleteLinked" questionnaireCompleteUnlinked: $ref: "#/components/examples/questionnaireCompleteUnlinked" + # Task - Appointment Booking Invitations + appointmentBookingInvitation: + $ref: "#/components/examples/appointmentBookingInvitation" + appointmentBookingInvitationWithExpiryDate: + $ref: "#/components/examples/appointmentBookingInvitationWithExpiryDate" + appointmentBookingInvitationStartedNotComplete: + $ref: "#/components/examples/appointmentBookingInvitationStartedNotComplete" + appointmentBookingInvitationCompleted: + $ref: "#/components/examples/appointmentBookingInvitationCompleted" + appointmentBookingInvitationCancelledNoResponse: + $ref: "#/components/examples/appointmentBookingInvitationCancelledNoResponse" + appointmentBookingInvitationRejected: + $ref: "#/components/examples/appointmentBookingInvitationRejected" + appointmentBookingInvitationRejectedConditionResolved: + $ref: "#/components/examples/appointmentBookingInvitationRejectedConditionResolved" # PIFU pifuZeroWaitingListZeroPifu: $ref: "#/components/examples/pifuZeroWaitingListZeroPifu" @@ -1867,7 +2189,7 @@ components: - $ref: "#/components/examples/correspondenceReadLinked" - $ref: "#/components/examples/correspondenceReadUnlinked" #- $ref: "#/components/examples/Attachment" # Not current supported - allQuestionnairestates: + allQuestionnaireStates: summary: 200 All Questionnaire states value: resourceType: Bundle @@ -1900,6 +2222,40 @@ components: - $ref: "#/components/examples/questionnairePartiallyCompleteUnlinked" - $ref: "#/components/examples/questionnaireCompleteLinked" - $ref: "#/components/examples/questionnaireCompleteUnlinked" + allAppointmentBookingInvitationStates: + summary: 200 All Appointment Booking Invitation states + value: + resourceType: Bundle + id: 665c2aab-a7c1-49f5-a128-686db221be81 + meta: + versionId: "3.3.4" + profile: + - https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreBundle + type: searchset + total: 1 + entry: + - fullUrl: https://api.service.nhs.uk/patient-care-aggregator-api/CarePlan/665c2aab-a7c1-49f5-a128-686db221be81 + search: + mode: match + resource: + resourceType: CarePlan + meta: + profile: + - https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreCarePlan + status: active + intent: order + subject: + identifier: + system: https://fhir.nhs.uk/Id/nhs-number + value: '9000000014' + activity: + - $ref: "#/components/examples/appointmentBookingInvitation" + - $ref: "#/components/examples/appointmentBookingInvitationWithExpiryDate" + - $ref: "#/components/examples/appointmentBookingInvitationStartedNotComplete" + - $ref: "#/components/examples/appointmentBookingInvitationCompleted" + - $ref: "#/components/examples/appointmentBookingInvitationCancelledNoResponse" + - $ref: "#/components/examples/appointmentBookingInvitationRejected" + - $ref: "#/components/examples/appointmentBookingInvitationRejectedConditionResolved" incompleteWaitingLists: summary: 200 One incomplete waiting list description: | @@ -4269,7 +4625,348 @@ components: system: https://fhir.nhs.uk/Id/ods-organization-code value: 'RXP' display: COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST - # PIFU + # Tasks + appointmentBookingInvitation: + summary: Fragment - Task for an invitation to book an appointment which has not been undertaken by the patient yet + value: + detail: + id: ad8baee0-f2b2-4258-ad25-a8de19c32c14 + status: requested + intent: plan + description: Book your Dermatology appointment + authored: '2025-07-16T09:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/ad8baee0-f2b2-4258-ad25-a8de19c32c14" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/ad8baee0-f2b2-4258-ad25-a8de19c32c14" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + appointmentBookingInvitationWithExpiryDate: + summary: Fragment - Task for an invitation to book an appointment which has an expiry date, and has not been undertaken by the patient yet + value: + detail: + id: 76c9d16f-1640-45f7-9455-17359eb38b03 + status: requested + intent: plan + description: Book your Cardiology appointment + authored: '2025-07-10T09:00:00.000Z' + restriction: + period: + start: '2025-07-16T09:00:00.000Z' + end: '2025-08-01T09:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment with expiry date" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/76c9d16f-1640-45f7-9455-17359eb38b03" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/76c9d16f-1640-45f7-9455-17359eb38b03" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + appointmentBookingInvitationStartedNotComplete: + summary: Fragment - Task for an invitation to book an appointment which has been started but not yet completed by the patient + value: + detail: + id: a814df2b-3e47-4f1a-9895-7e987bcdf5d6 + status: in-progress + intent: plan + description: Book your Oncology appointment + authored: '2025-07-10T09:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/a814df2b-3e47-4f1a-9895-7e987bcdf5d6" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/a814df2b-3e47-4f1a-9895-7e987bcdf5d6" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + appointmentBookingInvitationCompleted: + summary: Fragment - Task for an invitation to book an appointment which has been completed by the patient + value: + detail: + id: 0d3d275b-b3f6-4419-a72a-f6f10f1bef94 + status: completed + intent: plan + description: Book your General Surgery appointment + authored: '2025-07-10T09:00:00.000Z' + lastModified: '2025-07-18T14:30:00.000Z' + focus: + type: Appointment + reference: "Appointment/067024ee-134c-45fe-aa04-1a8544653c8f" + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/0d3d275b-b3f6-4419-a72a-f6f10f1bef94" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/0d3d275b-b3f6-4419-a72a-f6f10f1bef94" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + appointmentBookingInvitationCancelledNoResponse: + summary: Fragment - Task for an invitation to book an appointment which has been cancelled due to a lack of action by the patient within the booking window + value: + detail: + id: 22dd1b13-6b74-49a2-9fee-89e4a079fdcb + status: cancelled + statusReason: no-response-within-booking-window + intent: plan + description: Book your Neurology appointment + authored: '2025-06-01T09:00:00.000Z' + lastModified: '2025-07-01T09:00:00.000Z' + restriction: + period: + start: '2025-06-01T09:00:00.000Z' + end: '2025-07-01T09:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/22dd1b13-6b74-49a2-9fee-89e4a079fdcb" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/22dd1b13-6b74-49a2-9fee-89e4a079fdcb" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + appointmentBookingInvitationRejected: + summary: Fragment - Task for an invitation to book an appointment which has been rejected by the patient within the booking window + value: + detail: + id: c293d1b5-a297-430a-8ffb-7b426854df93 + status: rejected + intent: plan + description: Book your Gastroenterology appointment + authored: '2025-07-16T09:00:00.000Z' + lastModified: '2025-07-17T10:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/c293d1b5-a297-430a-8ffb-7b426854df93" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/c293d1b5-a297-430a-8ffb-7b426854df93" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + appointmentBookingInvitationRejectedConditionResolved: + summary: Fragment - Task for an invitation to book an appointment which has been rejected by the patient due to an improvement in their condition + value: + detail: + id: 5d86e89b-53dc-4ed2-b296-bbf31b5333c2 + status: rejected + statusReason: condition-resolved + intent: plan + description: Book your Rheumatology appointment + authored: '2025-07-16T09:00:00.000Z' + lastModified: '2025-07-19T11:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + display: "Appointment Booking Invitation" + text: "Invitation to book an appointment" + reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/5d86e89b-53dc-4ed2-b296-bbf31b5333c2" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/5d86e89b-53dc-4ed2-b296-bbf31b5333c2" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + # Questionnaire Tasks (using new Task resource) + pifuQuestionnaireTask: + summary: Fragment - Task for a PIFU questionnaire to be completed by the patient + value: + detail: + id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c + status: requested + intent: plan + description: Dermatology PIFU follow-up questionnaire + authored: '2025-06-20T18:00:00.000Z' + restriction: + period: + start: '2025-06-20T18:00:00.000Z' + end: '2025-12-20T00:00:00.000Z' + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" + code: "pifu-triage" + display: "PIFU Triage Questionnaire" + text: "Patient Initiated Follow-Up Questionnaire" + reasonReference: + type: Questionnaire + reference: "https://my.portal.com/Questionnaire/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction" + valueCoding: + system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" + code: "330" + display: "Dermatology" + preAssessmentQuestionnaireTask: + summary: Fragment - Task for a pre-assessment questionnaire linked to an appointment + value: + detail: + id: b519a5f2-dc78-417c-a5aa-1d62d889787b + status: in-progress + intent: plan + description: Orthopaedic Surgery pre-assessment questionnaire + authored: '2025-06-15T09:00:00.000Z' + lastModified: '2025-06-18T14:30:00.000Z' + restriction: + period: + start: '2025-06-15T09:00:00.000Z' + end: '2025-07-15T09:00:00.000Z' + focus: + type: Appointment + reference: "Appointment/4a3836f5-2d42-4d3e-87c1-680173b7fa5c" + for: + type: Patient + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000002" + owner: + type: Organization + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RXP" + display: "COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" + code: "pre-assessment" + display: "Pre-Assessment Questionnaire" + text: "Pre-assessment Questionnaire for upcoming appointment" + reasonReference: + type: Questionnaire + reference: "https://my.portal.com/Questionnaire/b519a5f2-dc78-417c-a5aa-1d62d889787b" + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: "https://my.portal.com/Task/b519a5f2-dc78-417c-a5aa-1d62d889787b" + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 pifuZeroWaitingListZeroPifu: summary: 200 - PIFU Zero Waiting List entries, Zero PIFU pathways description: Scenario 1 - Zero Waiting List entries, Zero PIFU pathways diff --git a/specification/patient-care-aggregator-api-producer-api-standards.yaml b/specification/patient-care-aggregator-api-producer-api-standards.yaml index d81497b..af3c9b3 100644 --- a/specification/patient-care-aggregator-api-producer-api-standards.yaml +++ b/specification/patient-care-aggregator-api-producer-api-standards.yaml @@ -242,12 +242,12 @@ paths: operationId: get-tasks description: | ## Overview - This endpoint returns a list of tasks for completion of questionnaires from a secondary care booking system for a given patient. + This endpoint returns a list of tasks, such as those for appointment booking invitations or for the completion of questionnaires, from a secondary care booking system for a given patient. It returns the tasks as a FHIR 'Bundle' containing FHIR 'Task' resources. Note that the above URL path is an example - you can use a different URL path if you prefer. - ## Questionnaires inclusion and exclusion rules + ## Task inclusion and exclusion rules The endpoint includes / excludes tasks as per the following rules: - NHS in England only: Only include tasks related to appointments for care settings within the NHS in England. - NHS Trusts only: Only include tasks related to appointments for acute, mental health or community care settings - not any other type. @@ -289,7 +289,7 @@ paths: # - $ref: "#/components/parameters/nhsdTargetIdentifier" responses: 2XX: - $ref: "#/components/responses/questionnaireHappyPath" + $ref: "#/components/responses/tasksHappyPath" 4XX: $ref: "#/components/responses/4XX" components: @@ -1052,7 +1052,7 @@ components: description: The Portal provider deep link URL. If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. example: "https://my.portal.com/Document/b710e648-c12e-4f66-80e2-9957a254900f" Task: - description: "FHIR TASK resource for the questionnaire" + description: "FHIR Task resource for the task" type: object required: - resourceType @@ -1063,7 +1063,7 @@ components: - for - authored - reasonReference - - owner + # removed 'owner' as it might need to be optional, as booking invites might offer a range of hospitals to choose from - reasonCode properties: resourceType: @@ -1091,7 +1091,7 @@ components: type: string example: "3a146c43-2b21-44e9-95bc-6f4849e504c8" basedOn: - description: Reference to the related CarePlan (Pathway). This reference should contain the pathway ID. This field is required for PIFU questionnaires to identify duplicate entries and is optional for other questionnaire types. + description: Reference to the related CarePlan (Pathway). This reference should contain the pathway ID. This field is required to identify duplicate entries and is optional for other task types. type: array minItems: 0 maxItems: 1 @@ -1124,25 +1124,55 @@ components: description: "Care pathway Identifier" example: "RBH5644312231" status: - description: "Status of the Task for the completion of the Questionnaire. See: https://build.fhir.org/valueset-task-status.html" + description: "Status of the task. See: https://build.fhir.org/valueset-task-status.html" type: string enum: - requested + # rejected is in FHIR R4, but will need to be added to our spec + - rejected - cancelled - in-progress - completed + statusReason: + # statusReason exists in FHIR R4 but we will need to define which codes can be used + # as it is a CodeableConcept, which allows us to extend it as we see fit + description: "Additional detail about the status of a task, for when further clarity is required, such as the reason a patient rejected an invite to book their appointment." + type: object + properties: + coding: + type: array + minItems: 1 + maxItems: 1 + items: + type: object + properties: + system: + type: string + enum: + - https://fhir.nhs.uk/CodeSystem/Task-StatusReason + code: + type: string + enum: + # This a just some possible codes; need more input for stakeholders to determine suitable list + - appointment-type-unsuitable + - condition-resolved + - location-unsuitable + - no-reason-given + - no-response-within-booking-window intent: description: "Hardcoded to plan. See: https://build.fhir.org/valueset-task-intent.html" type: string enum: - plan description: - description: "The patient-friendly, standardised title of the questionnaire that is suitable for display to patients. This value should match the name shown in your own interface and should follow the structure {Specialty name} {Questionnaire type}. If the questionnaire is linked to an appointment, the specialty should align with that appointment. For Patient Initiated Follow-Up (PIFU) questionnaires, the questionnaire type should not be included. The values presented within this field are required to be provided for Data Quality Assurance." + # Might need to extend this description to mention appointment bookings + description: "The patient-friendly, standardised title of the task that is suitable for display to patients. For questionnaires this value should match the name shown in your own interface and should follow the structure {Specialty name} {Questionnaire type}. If the questionnaire is linked to an appointment, the specialty should align with that appointment. For Patient Initiated Follow-Up (PIFU) questionnaires, the questionnaire type should not be included. The values presented within this field are required to be provided for Data Quality Assurance." type: string example: Dermatology pre-assessment questionnaire focus: + # This is optional and wouldn't apply to invites, as the appointment wouldn't exist type: object - description: Appointment reference to the appointments this questionnaire relates to. + description: Appointment reference to the appointments this task relates to (optional). Not required for appointment booking invites. required: - type - reference @@ -1158,7 +1188,7 @@ components: example: https://my.portal.com/fhir/R4/Appointment/ec2458f2-1e24-41c8-b71b-0e701af7583d for: type: object - description: Patient whom the questionnaire relates to. + description: Patient whom the task relates to. required: - type - identifier @@ -1185,40 +1215,47 @@ components: example: "9123456789" authored: type: string - description: Date the questionnaire was first made available to a patient in a UTC format. + description: Date the task was first made available to a patient in a UTC format. example: "2021-06-13T12:30:00+00:00" lastModified: type: string - description: Records the date and time (UTC) the questionnaire was completed by the patient. For Patient Initiated Follow-up (PIFU) feature, this field represents the date and time the patient last requested a follow-up appointment, and applies only to that individual PIFU request. This date must be greater than or equal to authored date. + description: Records the date and time (UTC) the task was completed by the patient. For Patient Initiated Follow-up (PIFU) feature, this field represents the date and time the patient last requested a follow-up appointment, and applies only to that individual PIFU request. This date must be greater than or equal to authored date. example: "2025-08-28T12:30:00+00:00" restriction: + # This is optional, but can be used for invites to signal when it must be actioned by type: object - description: Constraints on the questionnaire. + description: Constraints on the task. properties: period: type: object properties: end: type: string - description: Indicates the end date for the questionnaire. For the Patient Initiated Follow-up (PIFU) feature, this represents the expiration date of the questionnaire. After this date has passed, the patient can no longer raise a follow-up request. + description: Indicates the end date for the task. For the Patient Initiated Follow-up (PIFU) feature, this represents the expiration date of the questionnaire. After this date has passed, the patient can no longer raise a follow-up request. For appointment booking invites, this date is when this invite expires. example: "2025-10-18T12:30:00+00:00" reasonReference: + # This mandatory, so its type enum will need to be extended to include invites + # Not sure why it is called "reasonReference"; doesn't seem like a suitable name to me type: object - description: Reference to the Questionnaire being requested. + description: Reference to the Task being requested. required: - type - reference properties: type: type: string - description: Questionnaire FHIR Resource + description: FHIR Resource enum: - "Questionnaire" + # Need to check if this should relate to the specific task, such as Invite to Book, or just be "Task" + - "AppointmentBooking" reference: type: string description: The Portal provider deep link URL. If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. example: "https://my.portal.com/Questionnaire/3a146c43-2b21-44e9-95bc-6f4849e504c8" owner: + # This might be a problem as it is mandatory, and for invite to book the patient + # would likely be given the choice of hospitals at which to have their appointment type: object description: Organization responsible for the patients care required: @@ -1249,15 +1286,16 @@ components: type: string example: Barnsley Hospital NHS Foundation Trust reasonCode: + # This is mandatory, so will need to be extended to include booking invites type: object - description: Reason for the Task, the request for a patient to complete a Questionnaire. + description: Reason for the Task, the request for a patient to complete a the Task. required: - coding - text properties: coding: type: object - description: Array of Coding for the type of questionnaire to be completed. + description: Array of Coding for the type of task to be completed. required: - system - code @@ -1265,27 +1303,29 @@ components: properties: system: type: string - description: URI to identifier Questionnaire types + description: URI to identify Task types enum: - https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type + # Proposed extension; should it be for a generic task or for an invite? + - https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type code: type: string - description: Questionnaire type code. For questionnaires that are part of the patient initiated follow-up (PIFU) feature, the questionnaire type code must be set to "pifu-triage". + description: Task type code. For questionnaires that are part of the patient initiated follow-up (PIFU) feature, the questionnaire type code must be set to "pifu-triage". example: CONS-Survey display: type: string - description: Questionnaire type + description: Task type example: Consultation Survey text: type: string - description: Questionnaire type + description: Task type example: Pre-consultation Survey extension: description: "FHIR extensions for Task resources." type: array items: anyOf: - - description: "Treatment function associated to the Questionnaire. Please note: this must be provided for any \"pifu-triage\" Questionnaires." + - description: "Treatment function associated to the Task. Please note: this must be provided for any \"pifu-triage\" Questionnaires." type: object required: - url @@ -1470,7 +1510,7 @@ components: $ref: "#/components/examples/emptyBundle" document: $ref: "#/components/examples/document" - questionnaireHappyPath: + tasksHappyPath: description: A successful request. headers: #X-Request-ID: @@ -1485,7 +1525,9 @@ components: emptyBundle: $ref: "#/components/examples/emptyBundle" questionnaire: - $ref: "#/components/examples/questionnaire" + $ref: "#/components/examples/taskQuestionnaire" + appointmentBookingInvite: + $ref: "#/components/examples/taskAppointmentBookingInvite" 4XX: description: | When the service is unable to serve a successful response a FHIR `OperationOutcome` resource should be returned with the relevant HTTP status code defined as follows: @@ -1769,7 +1811,7 @@ components: - attachment: contentType: "application/pdf" url: "https://my.portal.com/Document/2f02f7ac-0de5-4271-81ad-92b69ead27e9" - questionnaire: + taskQuestionnaire: summary: 200 Example Patient with a Questionnaire value: resourceType: Bundle @@ -1820,6 +1862,57 @@ components: system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" code: "330" display: "Dermatology" + taskAppointmentBookingInvite: + summary: 200 Example Patient with a Appointment Booking Invitation + value: + resourceType: Bundle + type: searchset + total: 1 + entry: + - fullUrl: "https://my.patientportal.co.uk/Task/3947e645-c7f9-4791-b5b5-386b97e4b271" + search: + mode: match + resource: + resourceType: Task + id: "6383658e-fef4-4b89-9f68-7af67ed8c382" + basedOn: + - type: "CarePlan" + identifier: + system: "https://fhir.nhs.uk/Id/PathwayId" + value: "RBH5644312231" + status: "requested" + intent: "plan" + description: "Invitation to Book a Video Consultation Appointment" + for: + type: "Patient" + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000014" + authoredOn: "2026-07-13T12:30:00+00:00" + restriction: + period: + end: "2026-07-13T18:00:00+00:00" + reasonReference: + type: "AppointmentBooking" + reference: "https://my.portal.com/AppointmentBooking/cdb83383-f17e-4bf7-8f40-342f7f7c7d8d" + owner: + type: "Organization" + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RFF" + display: "Barnsley Hospital NHS Foundation Trust" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "VIDEO-CONSULT" + display: "Video Consultation" + text: "Online Video Consultation" + extension: + - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction" + valueCoding: + system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" + code: "330" + display: "Dermatology" missingNhsNumber: summary: 400 Missing patient:identifier search parameter description: No patient:identifier as a search parameter.