From 9073c7d0e5f17fe67d5e1349496973c5fc9b72f9 Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Wed, 15 Jul 2026 12:36:02 +0100 Subject: [PATCH 01/13] modify task resource in producer spec so that it is suitable for a variety of tasks rather than just questionnaire responses --- ...aggregator-api-producer-api-standards.yaml | 80 ++++++++++++++----- 1 file changed, 60 insertions(+), 20 deletions(-) diff --git a/specification/patient-care-aggregator-api-producer-api-standards.yaml b/specification/patient-care-aggregator-api-producer-api-standards.yaml index d81497b..00b9d21 100644 --- a/specification/patient-care-aggregator-api-producer-api-standards.yaml +++ b/specification/patient-care-aggregator-api-producer-api-standards.yaml @@ -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 From 1a7e6ce4b02edeaa04f5be275da965bab52a29c9 Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Wed, 15 Jul 2026 12:38:53 +0100 Subject: [PATCH 02/13] add task resource to the consumer spec so that a variety of task details, such as booking invites and questionnaire responses can be communicated --- ...ient-care-aggregator-api-consumer-api.yaml | 235 +++++++++++++++++- 1 file changed, 233 insertions(+), 2 deletions(-) diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index b669ffa..cef651f 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,236 @@ components: description: ODS Organisation name (NHS Trust) type: string example: THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST + Task: + # The layout of the proposed Task resource contains all the fields from the Questionnaire resource + # so that it could also be used to represent a questionnaire response and then the Questionnaire + # resource could be deprecated. + description: A summary of the task to be actioned by the patient. + type: object + required: + - detail + properties: + detail: + description: Details of the task. + type: object + required: + # The required fields match those in the Questionnaire resource, as retain interoperability + - kind + - status + - description + properties: + id: + description: Identifier for the Task + type: string + example: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c + kind: + # This is mandatory, so it will need to be extended whenever a new task type is needed + description: Type of task activity. + type: string + enum: + - QuestionnaireResponse + - AppointmentBookingInvite + status: + description: The status of the task, if it has been started or completed by the patient. + type: string + enum: + - not-started + - in-progress + - completed + - cancelled + # rejected is in FHIR R$, but not currently in our spec + - rejected + statusReason: + # statusReason is in FHIR R4, and very flexible because it is a CodeableConcept, so we could chose to pass the same codes through from the producer spec + # or preprend these codes with status they refer to, such as "rejected-condition-resolved". + description: Additional information to clarify the reason for the status (optional). Can be used to indicate why an appointment booking invitation has been rejected, such as when the patient has recovered, or offered appointment type is no desired by the patient. + type: string + enum: + - appointment-type-unsuitable + - condition-resolved + - location-unsuitable + - no-reason-given + - no-response-within-booking-window + extension: + description: FHIR extension wrapper for various country-specific data items. + type: array + items: + anyOf: + - description: URL for a patient-facing web application for the referral or booking. Always present. + type: object + required: + - url + - valueUrl + - extension + properties: + url: + description: FHIR extension type. + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: + description: The URL itself. + type: string + example: https://refer.nhs.uk/nhslogin?ubrn=808993698030 + - description: FHIR extension wrapper for the details of which upstream application the referral or booking came from. + type: array + items: + description: Unique identifier for the upstream application the referral or booking came from. + type: object + required: + - url + - valueCode + properties: + url: + description: FHIR extension type for the identifier. + type: string + enum: + - client-id + valueCode: + description: The identifier itself. + type: string + example: ers-01 + - description: Reference to Appointment extension (optional). To be included when an Appointment has been booked; will be absent when task is for an invitation to book an appointment. + type: object + required: + - url + - valueReference + properties: + url: + description: FHIR extension uri for the Appointment Reference. + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Linked-Resource + valueReference: + description: The Reference to Appointment which this Questionnaire is associated to. + type: object + required: + - reference + properties: + reference: + type: string + example: Appointment/caa99978-05ab-4473-8280-e77ebfe797c4 + - description: FHIR extension for Task type coding + # This will likely need to be created so the NHS App can distinguish between Questionnaires and other + # tasks, such as booking invites + type: object + required: + - url + - valueCoding + properties: + url: + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type + description: Extension URL indicating the type of task. + valueCoding: + type: object + required: + - system + - code + properties: + system: + type: string + enum: + - https://fhir.nhs.uk/CodeSystem/Task-Type + code: + type: string + example: appointment-booking-invite + - description: FHIR extension for Questionnaire type coding + # The existing Questionnaire coding is retained for backwards compatibility with the Questionnaire + # resource. The Task type coding extension above could eventually be extended to include any + # required questionnaire type codes, so this extension could eventually be dropped. + type: object + required: + - url + - valueCoding + properties: + url: + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type + description: Extension URL indicating the type of Questionnaire. + valueCoding: + type: object + required: + - system + - code + properties: + system: + type: string + enum: + - https://fhir.nhs.uk/CodeSystem/Questionnaire-Type + code: + type: string + example: pifu-triage + - description: FHIR extension for Task last modified date + type: object + required: + - url + - valueDate + properties: + url: + description: Extension URL for the Task last modified date. + type: string + enum: + - https://fhir.nhs.uk/StructureDefinition/Extension-Task-LastModifiedDate + valueDate: + description: The date that this task was last modified by the user. + type: string + example: '2025-06-23' + description: + description: Description of the task to be displayed to the patient. _Note; this is freetext and can contain some data quality issues._ + type: string + example: Appointment Booking Invitation + scheduledPeriod: + description: The period over which the activity is to occur. + type: object + required: + - start + properties: + start: + description: The effective start date of the task i.e. the date the appointment booking invite was first available to the patient to complete. + type: string + example: '2025-06-20T18:00:00.000Z' + end: + description: The effective end date of the task i.e. the date by which the patient should complete the appointment booking task. + type: string + example: '2025-12-20T00:00:00.000Z' + performer: + description: The organisation responsible for the Task. + type: array + minItems: 1 + maxItems: 1 + items: + description: The organisation the task is from. + type: object + required: + - type + - display + - identifier + properties: + type: + description: Type of entity. + type: string + enum: + - Organization + identifier: + type: object + required: + - system + - value + properties: + system: + type: string + enum: + - "https://fhir.nhs.uk/Id/ods-organization-code" + value: + type: string + example: "RTD" + display: + description: ODS Organisation name (NHS Trust) + type: string + example: THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST OperationOutcome: description: A FHIR `OperationOutcome` resource containing details of the issues that have occurred. type: object From 7ebc8822ec8d9f653d0f8776ff0ad7a1050369e0 Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Thu, 16 Jul 2026 09:07:44 +0100 Subject: [PATCH 03/13] update producer task overview --- .../patient-care-aggregator-api-producer-api-standards.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/patient-care-aggregator-api-producer-api-standards.yaml b/specification/patient-care-aggregator-api-producer-api-standards.yaml index 00b9d21..cf4f78b 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. From 31daaf1d0e293e4e9017ccaa0dfb5ce0e62db390 Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Thu, 16 Jul 2026 11:28:13 +0100 Subject: [PATCH 04/13] add consumer spec task examples --- ...ient-care-aggregator-api-consumer-api.yaml | 121 +++++++++++++++++- 1 file changed, 119 insertions(+), 2 deletions(-) diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index cef651f..7f1f0cf 100644 --- a/specification/patient-care-aggregator-api-consumer-api.yaml +++ b/specification/patient-care-aggregator-api-consumer-api.yaml @@ -1298,7 +1298,7 @@ components: enum: - https://fhir.nhs.uk/StructureDefinition/Extension-Linked-Resource valueReference: - description: The Reference to Appointment which this Questionnaire is associated to. + description: The Reference to Appointment which this Task is associated to. type: object required: - reference @@ -1627,6 +1627,8 @@ components: $ref: "#/components/examples/allDocumentStates" allQuestionnairestates: $ref: "#/components/examples/allQuestionnairestates" + allTaskStates: + $ref: "#/components/examples/allTaskStates" incompleteWaitingLists: $ref: "#/components/examples/incompleteWaitingLists" incompleteWaitingListBreastScreening: # Not current supported @@ -1784,6 +1786,21 @@ components: $ref: "#/components/examples/questionnaireCompleteLinked" questionnaireCompleteUnlinked: $ref: "#/components/examples/questionnaireCompleteUnlinked" + # Tasks + 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" @@ -2098,7 +2115,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 @@ -4500,6 +4517,106 @@ components: system: https://fhir.nhs.uk/Id/ods-organization-code value: 'RXP' display: COUNTY DURHAM AND DARLINGTON NHS FOUNDATION TRUST + # 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 + kind: AppointmentBookingInvite + status: not-started + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/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 + kind: AppointmentBookingInvite + status: not-started + scheduledPeriod: + start: '2025-07-16T09:00:00.000Z' + end: '2025-08-01T09:00:00.000Z' + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/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 + kind: AppointmentBookingInvite + status: in-progress + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/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 + kind: AppointmentBookingInvite + status: completed + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/0d3d275b-b3f6-4419-a72a-f6f10f1bef94 + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Linked-Resource + valueReference: + reference: Appointment/067024ee-134c-45fe-aa04-1a8544653c8f + 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 + kind: AppointmentBookingInvite + status: cancelled + statusReason: no-response-within-booking-window + scheduledPeriod: + start: '2025-06-01T09:00:00.000Z' + end: '2025-07-01T09:00:00.000Z' + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/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 + kind: AppointmentBookingInvite + status: rejected + scheduledPeriod: + start: '2025-07-16T09:00:00.000Z' + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/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 cancelled by the patient due to an improvement in their condition + value: + detail: + id: 5d86e89b-53dc-4ed2-b296-bbf31b5333c2 + kind: AppointmentBookingInvite + status: rejected + statusReason: condition-resolved + scheduledPeriod: + start: '2025-07-16T09:00:00.000Z' + extension: + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link + valueUrl: https://my.portal.com/AppointmentBookingInvite/5d86e89b-53dc-4ed2-b296-bbf31b5333c2 + - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: myportal-01 # PIFU pifuZeroWaitingListZeroPifu: summary: 200 - PIFU Zero Waiting List entries, Zero PIFU pathways From 2d4f6cf90857a974eb0c376215e700e81301076b Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Thu, 16 Jul 2026 11:51:58 +0100 Subject: [PATCH 05/13] add more examples to consumer spec for allAppointmentBookingInvitationStates --- ...ient-care-aggregator-api-consumer-api.yaml | 42 +++++++++++++++++-- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index 7f1f0cf..cd33ea8 100644 --- a/specification/patient-care-aggregator-api-consumer-api.yaml +++ b/specification/patient-care-aggregator-api-consumer-api.yaml @@ -1627,8 +1627,8 @@ components: $ref: "#/components/examples/allDocumentStates" allQuestionnairestates: $ref: "#/components/examples/allQuestionnairestates" - allTaskStates: - $ref: "#/components/examples/allTaskStates" + allAppointmentBookingInvitationStates: + $ref: "#/components/examples/allAppointmentBookingInvitationStates" incompleteWaitingLists: $ref: "#/components/examples/incompleteWaitingLists" incompleteWaitingListBreastScreening: # Not current supported @@ -1773,7 +1773,7 @@ components: $ref: "#/components/examples/correspondenceReadUnlinked" #Attachment: # $ref: "#/components/examples/Attachment" - # Questionnaires + # Task - Questionnaires questionnaireIncompleteLinked: $ref: "#/components/examples/questionnaireIncompleteLinked" questionnaireIncompleteUnlinked: @@ -1786,7 +1786,7 @@ components: $ref: "#/components/examples/questionnaireCompleteLinked" questionnaireCompleteUnlinked: $ref: "#/components/examples/questionnaireCompleteUnlinked" - # Tasks + # Task - Appointment Booking Invitations appointmentBookingInvitation: $ref: "#/components/examples/appointmentBookingInvitation" appointmentBookingInvitationWithExpiryDate: @@ -2148,6 +2148,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: | From 0916cbf950915d516fd4c94b158dafd4b6f6fc56 Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:33:55 +0100 Subject: [PATCH 06/13] add task examples to producer spec --- ...aggregator-api-producer-api-standards.yaml | 76 ++++++++++++++++++- 1 file changed, 72 insertions(+), 4 deletions(-) diff --git a/specification/patient-care-aggregator-api-producer-api-standards.yaml b/specification/patient-care-aggregator-api-producer-api-standards.yaml index cf4f78b..068d387 100644 --- a/specification/patient-care-aggregator-api-producer-api-standards.yaml +++ b/specification/patient-care-aggregator-api-producer-api-standards.yaml @@ -289,7 +289,8 @@ paths: # - $ref: "#/components/parameters/nhsdTargetIdentifier" responses: 2XX: - $ref: "#/components/responses/questionnaireHappyPath" + $ref: "#/components/responses/taskQuestionnaireHappyPath" + $ref: "#/components/responses/taskAppointmentBookingInvitationHappyPath" 4XX: $ref: "#/components/responses/4XX" components: @@ -1510,7 +1511,7 @@ components: $ref: "#/components/examples/emptyBundle" document: $ref: "#/components/examples/document" - questionnaireHappyPath: + tasksQuestionnaireHappyPath: description: A successful request. headers: #X-Request-ID: @@ -1525,7 +1526,23 @@ components: emptyBundle: $ref: "#/components/examples/emptyBundle" questionnaire: - $ref: "#/components/examples/questionnaire" + $ref: "#/components/examples/taskQuestionnaire" + tasksAppointmentBookingInvitationHappyPath: + description: A successful request. + headers: + #X-Request-ID: + # $ref: "#/components/headers/xRequestId" + X-Correlation-ID: + $ref: "#/components/headers/xCorrelationId" + content: + application/fhir+json: + schema: + $ref: "#/components/schemas/Task" + examples: + emptyBundle: + $ref: "#/components/examples/emptyBundle" + 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: @@ -1809,7 +1826,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 @@ -1860,6 +1877,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. From 8d7513c88f33f93420a245f40d19ad5e654e07d1 Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Thu, 16 Jul 2026 15:25:18 +0100 Subject: [PATCH 07/13] correct producer spec task response --- ...aggregator-api-producer-api-standards.yaml | 21 +++---------------- 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/specification/patient-care-aggregator-api-producer-api-standards.yaml b/specification/patient-care-aggregator-api-producer-api-standards.yaml index 068d387..af3c9b3 100644 --- a/specification/patient-care-aggregator-api-producer-api-standards.yaml +++ b/specification/patient-care-aggregator-api-producer-api-standards.yaml @@ -289,8 +289,7 @@ paths: # - $ref: "#/components/parameters/nhsdTargetIdentifier" responses: 2XX: - $ref: "#/components/responses/taskQuestionnaireHappyPath" - $ref: "#/components/responses/taskAppointmentBookingInvitationHappyPath" + $ref: "#/components/responses/tasksHappyPath" 4XX: $ref: "#/components/responses/4XX" components: @@ -1511,7 +1510,7 @@ components: $ref: "#/components/examples/emptyBundle" document: $ref: "#/components/examples/document" - tasksQuestionnaireHappyPath: + tasksHappyPath: description: A successful request. headers: #X-Request-ID: @@ -1527,22 +1526,8 @@ components: $ref: "#/components/examples/emptyBundle" questionnaire: $ref: "#/components/examples/taskQuestionnaire" - tasksAppointmentBookingInvitationHappyPath: - description: A successful request. - headers: - #X-Request-ID: - # $ref: "#/components/headers/xRequestId" - X-Correlation-ID: - $ref: "#/components/headers/xCorrelationId" - content: - application/fhir+json: - schema: - $ref: "#/components/schemas/Task" - examples: - emptyBundle: - $ref: "#/components/examples/emptyBundle" appointmentBookingInvite: - $ref: "#/components/examples/taskAppointmentBookingInvite" + $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: From 986cb759f79d2d003e76f94e5f47fe25c35db40c Mon Sep 17 00:00:00 2001 From: Simeon Parris <275962675+simeonparris-nhs@users.noreply.github.com> Date: Thu, 16 Jul 2026 15:28:51 +0100 Subject: [PATCH 08/13] correct spelling of allQuestionnaireStates in consumer spec --- specification/patient-care-aggregator-api-consumer-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index cd33ea8..8e7ce0e 100644 --- a/specification/patient-care-aggregator-api-consumer-api.yaml +++ b/specification/patient-care-aggregator-api-consumer-api.yaml @@ -1625,8 +1625,8 @@ 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: From 44e6d2b2700400b30fb62d1448f076fa9a8de4e6 Mon Sep 17 00:00:00 2001 From: Edward Bowyer <285946832+edwardbowyer-nhs@users.noreply.github.com> Date: Mon, 20 Jul 2026 12:38:18 +0100 Subject: [PATCH 09/13] Aligned Task consumer spec more closely with Producer spec, generic while backwards compatible --- TASK_RESOURCE_ALIGNMENT_SUMMARY.md | 245 ++++++ ...ient-care-aggregator-api-consumer-api.yaml | 701 +++++++++++++----- 2 files changed, 753 insertions(+), 193 deletions(-) create mode 100644 TASK_RESOURCE_ALIGNMENT_SUMMARY.md diff --git a/TASK_RESOURCE_ALIGNMENT_SUMMARY.md b/TASK_RESOURCE_ALIGNMENT_SUMMARY.md new file mode 100644 index 0000000..85a10d1 --- /dev/null +++ b/TASK_RESOURCE_ALIGNMENT_SUMMARY.md @@ -0,0 +1,245 @@ +# Task Resource Alignment Summary + +## Overview +The Consumer spec Task resource has been updated to align with the Producer spec's generic FHIR-based Task implementation. This enables the Task resource to support multiple use cases (questionnaires, appointment booking invites, and future task types) while maintaining backwards compatibility with the existing Questionnaire resource. + +## Why This Change? + +### Previous Implementation +- **Questionnaire-centric**: The Consumer Task resource was essentially a copy of the Questionnaire resource with additional fields for appointment booking invites +- **Limited extensibility**: The `kind` enum was rigid and required updates for each new task type +- **Misaligned with Producer spec**: The Consumer spec Task didn't follow the producer-side FHIR Task pattern +- **Redundancy**: Similar fields and logic across Questionnaire and Task resources + +### New Implementation +- **Generic task framework**: Task resource can represent any patient action (questionnaires, booking invites, etc.) +- **FHIR R4 aligned**: Follows standard FHIR Task structure with fields like `status`, `intent`, `reasonCode`, `reasonReference` +- **Producer-spec aligned**: Matches the Producer API standards for consistency across the aggregator ecosystem +- **Future-proof**: Extensible via `reasonCode` and extensions for new task types +- **Cleaner architecture**: Single generic Task resource instead of type-specific variants + +## Key Changes + +### Removed Fields +- **`kind`** → Replaced by `reasonCode` (provides more semantic meaning) +- **`scheduledPeriod`** → Replaced by `restriction.period` (FHIR standard) +- **`performer`** → Replaced by `owner` (FHIR standard terminology) + +### Added Fields +| Field | Type | Required | Purpose | +|-------|------|----------|---------| +| `id` | string | Yes | Globally unique identifier for the task | +| `identifier` | object | No | System-specific identifier (portal database ID) | +| `intent` | string | Yes | Always "plan" - indicates task intent | +| `authored` | date-time | Yes | When task became available to patient | +| `lastModified` | date-time | No | When task was last modified by patient | +| `restriction.period` | object | No | Start/end dates for task deadline | +| `focus` | object | No | Reference to linked Appointment (if applicable) | +| `for` | object | Yes | Patient identifier (NHS number) | +| `owner` | object | Yes | Responsible organization (provider) | +| `basedOn` | array | No | Optional reference to care pathway | +| `reasonCode` | object | Yes | Codes and text for task type classification | +| `reasonReference` | object | Yes | Reference to Questionnaire or AppointmentBooking | + +### Modified Fields +- **`status`**: Changed from `["not-started", "in-progress", "completed", "cancelled"]` to FHIR-compliant `["requested", "rejected", "cancelled", "in-progress", "completed"]` +- **`statusReason`**: Now structured as codeable concept (ready for future expansion) +- **`description`**: Enhanced with clearer guidance for both questionnaires and invites +- **`extension`**: Streamlined to include Portal Link, Client ID, and Treatment Function (for PIFU only) + +## Task Type Classification + +### Using `reasonCode` to Distinguish Task Types + +The new `reasonCode` structure replaces the old `kind` enum and provides semantic clarity: + +#### For Questionnaires: +```yaml +reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" + code: "pifu-triage" # or other questionnaire codes + display: "PIFU Triage Questionnaire" + text: "Patient Initiated Follow-Up Questionnaire" +``` + +#### For Appointment Booking Invites: +```yaml +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" +``` + +## Backwards Compatibility + +### Questionnaire Resource Preserved +- The existing `Questionnaire` resource remains **unchanged** +- Current consumers can continue using the Questionnaire resource without modification +- No breaking changes to the Questionnaire schema + +### Migration Path +1. **Phase 1 (Current)**: Both Task and Questionnaire resources available +2. **Phase 2 (Future)**: Clients should migrate to using Task for new questionnaire implementations +3. **Phase 3 (Future)**: Questionnaire resource may be deprecated (with advance notice) + +## Data Models + +### Appointment Booking Invite (Task) +```yaml +id: ad8baee0-f2b2-4258-ad25-a8de19c32c14 +status: requested +intent: plan +description: Book your Dermatology appointment +authored: '2025-07-16T09:00:00.000Z' +reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "appointment-booking-invite" + text: "Invitation to book an appointment" +reasonReference: + type: AppointmentBooking + reference: "https://my.portal.com/AppointmentBooking/ad8baee0-f2b2-4258-ad25-a8de19c32c14" +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" +``` + +### Questionnaire (Task) +```yaml +id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c +status: requested +intent: plan +description: Dermatology PIFU follow-up questionnaire +authored: '2025-06-20T18:00:00.000Z' +reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" + code: "pifu-triage" + 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-Task-TreatmentFunction" + valueCoding: + system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" + code: "330" + display: "Dermatology" +``` + +## Examples Updated + +### Appointment Booking Invites (6 examples) +1. ✅ Basic invitation (not started) +2. ✅ With expiry date (requested, not started) +3. ✅ Started but incomplete (in-progress) +4. ✅ Completed (with linked appointment) +5. ✅ Cancelled (no response within booking window) +6. ✅ Rejected (patient condition resolved) + +### Questionnaires (2 new examples) +1. ✅ PIFU questionnaire (with treatment function extension) +2. ✅ Pre-assessment questionnaire (linked to appointment) + +## Implementation Notes + +### For Consumer API Users +- **No immediate changes required** if using Questionnaire resource +- **Optional migration**: Adopt Task resource for future questionnaire implementations +- **New integrations**: Use Task resource for all task types + +### For Portal Providers (Producer API) +- **Already implemented**: Producer spec Task resource remains unchanged +- **Consistency**: Consumer spec now aligns with Producer spec +- **Contract testing**: Ensure portal systems work with both old Questionnaire and new Task patterns during transition + +### For the Aggregator Service +- **Data mapping**: When aggregating from portals, map incoming Task data to both Questionnaire (for backwards compatibility) and Task resources +- **Gradual rollout**: Transition consumers to Task resource over time +- **Validation**: Ensure both resourceType patterns are properly validated + +## Status Values Mapping + +| Old (Questionnaire) | New (Task) | Meaning | +|-------------------|-----------|---------| +| `not-started` | `requested` | Task available but not yet started | +| `in-progress` | `in-progress` | Task started by patient | +| `completed` | `completed` | Task finished by patient | +| `cancelled` | `cancelled` | Task cancelled by system or patient | +| (new) | `rejected` | Patient explicitly declined task | + +## Extension Framework + +The streamlined extensions provide: + +1. **Portal Link** (required) + - Deep link to patient-facing portal interface + - System: `https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link` + +2. **Client ID** (optional) + - Upstream system identifier + - System: `https://fhir.nhs.uk/StructureDefinition/Extension-Client-id` + +3. **Treatment Function** (conditional) + - For PIFU questionnaires only + - System: `https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction` + +## Future Enhancements + +The new Task structure enables: +- ✅ Appointment booking invites +- ✅ Pre-assessment questionnaires +- ✅ PIFU questionnaires +- 🔄 Referral action tasks (future) +- 🔄 Document review tasks (future) +- 🔄 Custom patient tasks (extensible via reasonCode) + +## Migration Checklist + +For NHS App and Consumer Implementations: +- [ ] Review and test new Task examples +- [ ] Update data models to support new fields (`intent`, `reasonCode`, `reasonReference`, `for`, `owner`) +- [ ] Implement logic to handle `reasonCode.system` for task type differentiation +- [ ] Handle optional fields appropriately (e.g., `focus` for incomplete booking invites) +- [ ] Add support for `statusReason` for rejection details +- [ ] Test rendering of both questionnaire and appointment booking tasks +- [ ] Maintain Questionnaire resource support during transition period +- [ ] Plan migration strategy for existing questionnaire implementations + +## Questions & Clarifications + +**Q: When will the Questionnaire resource be deprecated?** +A: No immediate deprecation. The Questionnaire resource will remain supported during a transition period (to be determined). We'll provide advance notice before any deprecation. + +**Q: Do I need to update my system immediately?** +A: No. Existing implementations using Questionnaire continue to work. Adopt Task resource for new implementations or when ready to migrate. + +**Q: How do I distinguish between task types?** +A: Use the `reasonCode.coding.system` field: +- Questionnaires: `Extension-Questionnaire-Type` +- Booking invites: `Extension-Task-Type` + +**Q: What about linked appointments?** +A: Use the `focus` field to reference an appointment: +- For completed booking invites: `focus.reference` points to the booked appointment +- For questionnaires before appointment: `focus` may be empty or optional + +**Q: Can I store custom data in Task?** +A: Yes, use extensions (array) to add custom fields following FHIR extension patterns. + +--- + +**Document Version**: 1.0 +**Last Updated**: 2026-07-20 +**Status**: Implementation Complete diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index 8e7ce0e..485a6ba 100644 --- a/specification/patient-care-aggregator-api-consumer-api.yaml +++ b/specification/patient-care-aggregator-api-consumer-api.yaml @@ -1198,10 +1198,7 @@ components: type: string example: THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST Task: - # The layout of the proposed Task resource contains all the fields from the Questionnaire resource - # so that it could also be used to represent a questionnaire response and then the Questionnaire - # resource could be deprecated. - description: A summary of the task to be actioned by the patient. + 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 @@ -1210,36 +1207,43 @@ components: description: Details of the task. type: object required: - # The required fields match those in the Questionnaire resource, as retain interoperability - - kind + - id - status - description + - authored + - reasonCode + - reasonReference properties: id: - description: Identifier for the Task + description: Globally unique identifier for the Task. To be persisted over time. type: string example: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c - kind: - # This is mandatory, so it will need to be extended whenever a new task type is needed - description: Type of task activity. - type: string - enum: - - QuestionnaireResponse - - AppointmentBookingInvite + 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, if it has been started or completed by the patient. + description: The status of the task as progressed by the patient. type: string enum: - - not-started + - requested + - rejected + - cancelled - in-progress - completed - - cancelled - # rejected is in FHIR R$, but not currently in our spec - - rejected statusReason: - # statusReason is in FHIR R4, and very flexible because it is a CodeableConcept, so we could chose to pass the same codes through from the producer spec - # or preprend these codes with status they refer to, such as "rejected-condition-resolved". - description: Additional information to clarify the reason for the status (optional). Can be used to indicate why an appointment booking invitation has been rejected, such as when the patient has recovered, or offered appointment type is no desired by the patient. + 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 @@ -1247,17 +1251,204 @@ components: - 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 extension wrapper for various country-specific data items. + 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 referral or booking. Always present. + - description: URL for a patient-facing web application for the task. Always present. type: object required: - url - valueUrl - - extension properties: url: description: FHIR extension type. @@ -1265,87 +1456,32 @@ components: enum: - https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link valueUrl: - description: The URL itself. + description: The Portal provider deep link URL to access the task. type: string - example: https://refer.nhs.uk/nhslogin?ubrn=808993698030 - - description: FHIR extension wrapper for the details of which upstream application the referral or booking came from. - type: array - items: - description: Unique identifier for the upstream application the referral or booking came from. - type: object - required: - - url - - valueCode - properties: - url: - description: FHIR extension type for the identifier. - type: string - enum: - - client-id - valueCode: - description: The identifier itself. - type: string - example: ers-01 - - description: Reference to Appointment extension (optional). To be included when an Appointment has been booked; will be absent when task is for an invitation to book an appointment. + 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 - - valueReference + - valueCode properties: url: - description: FHIR extension uri for the Appointment Reference. + description: FHIR extension type. type: string enum: - - https://fhir.nhs.uk/StructureDefinition/Extension-Linked-Resource - valueReference: - description: The Reference to Appointment which this Task is associated to. - type: object - required: - - reference - properties: - reference: - type: string - example: Appointment/caa99978-05ab-4473-8280-e77ebfe797c4 - - description: FHIR extension for Task type coding - # This will likely need to be created so the NHS App can distinguish between Questionnaires and other - # tasks, such as booking invites - type: object - required: - - url - - valueCoding - properties: - url: + - https://fhir.nhs.uk/StructureDefinition/Extension-Client-id + valueCode: + description: Portal system identifier. type: string - enum: - - https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type - description: Extension URL indicating the type of task. - valueCoding: - type: object - required: - - system - - code - properties: - system: - type: string - enum: - - https://fhir.nhs.uk/CodeSystem/Task-Type - code: - type: string - example: appointment-booking-invite - - description: FHIR extension for Questionnaire type coding - # The existing Questionnaire coding is retained for backwards compatibility with the Questionnaire - # resource. The Task type coding extension above could eventually be extended to include any - # required questionnaire type codes, so this extension could eventually be dropped. + example: "myportal-01" + - description: Treatment function associated to the Task. Must be provided for PIFU questionnaires. type: object - required: - - url - - valueCoding properties: url: + description: Extension URL for treatment function. type: string enum: - - https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type - description: Extension URL indicating the type of Questionnaire. + - "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction" valueCoding: type: object required: @@ -1353,80 +1489,18 @@ components: - code properties: system: + description: Coding system for treatment function. type: string enum: - - https://fhir.nhs.uk/CodeSystem/Questionnaire-Type + - "https://fhir.nhs.uk/CodeSystem/Specialty-1" code: + description: Treatment function code. type: string - example: pifu-triage - - description: FHIR extension for Task last modified date - type: object - required: - - url - - valueDate - properties: - url: - description: Extension URL for the Task last modified date. - type: string - enum: - - https://fhir.nhs.uk/StructureDefinition/Extension-Task-LastModifiedDate - valueDate: - description: The date that this task was last modified by the user. - type: string - example: '2025-06-23' - description: - description: Description of the task to be displayed to the patient. _Note; this is freetext and can contain some data quality issues._ - type: string - example: Appointment Booking Invitation - scheduledPeriod: - description: The period over which the activity is to occur. - type: object - required: - - start - properties: - start: - description: The effective start date of the task i.e. the date the appointment booking invite was first available to the patient to complete. - type: string - example: '2025-06-20T18:00:00.000Z' - end: - description: The effective end date of the task i.e. the date by which the patient should complete the appointment booking task. - type: string - example: '2025-12-20T00:00:00.000Z' - performer: - description: The organisation responsible for the Task. - type: array - minItems: 1 - maxItems: 1 - items: - description: The organisation the task is from. - type: object - required: - - type - - display - - identifier - properties: - type: - description: Type of entity. - type: string - enum: - - Organization - identifier: - type: object - required: - - system - - value - properties: - system: - type: string - enum: - - "https://fhir.nhs.uk/Id/ods-organization-code" - value: - type: string - example: "RTD" - display: - description: ODS Organisation name (NHS Trust) - type: string - example: THE NEWCASTLE UPON TYNE HOSPITALS NHS FOUNDATION TRUST + 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 @@ -4557,11 +4631,33 @@ components: value: detail: id: ad8baee0-f2b2-4258-ad25-a8de19c32c14 - kind: AppointmentBookingInvite - status: not-started + 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/AppointmentBookingInvite/ad8baee0-f2b2-4258-ad25-a8de19c32c14 + valueUrl: "https://my.portal.com/Task/ad8baee0-f2b2-4258-ad25-a8de19c32c14" - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id valueCode: myportal-01 appointmentBookingInvitationWithExpiryDate: @@ -4569,14 +4665,37 @@ components: value: detail: id: 76c9d16f-1640-45f7-9455-17359eb38b03 - kind: AppointmentBookingInvite - status: not-started - scheduledPeriod: - start: '2025-07-16T09:00:00.000Z' - end: '2025-08-01T09:00:00.000Z' + 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/AppointmentBookingInvite/76c9d16f-1640-45f7-9455-17359eb38b03 + valueUrl: "https://my.portal.com/Task/76c9d16f-1640-45f7-9455-17359eb38b03" - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id valueCode: myportal-01 appointmentBookingInvitationStartedNotComplete: @@ -4584,11 +4703,33 @@ components: value: detail: id: a814df2b-3e47-4f1a-9895-7e987bcdf5d6 - kind: AppointmentBookingInvite 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/AppointmentBookingInvite/a814df2b-3e47-4f1a-9895-7e987bcdf5d6 + valueUrl: "https://my.portal.com/Task/a814df2b-3e47-4f1a-9895-7e987bcdf5d6" - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id valueCode: myportal-01 appointmentBookingInvitationCompleted: @@ -4596,30 +4737,77 @@ components: value: detail: id: 0d3d275b-b3f6-4419-a72a-f6f10f1bef94 - kind: AppointmentBookingInvite 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/AppointmentBookingInvite/0d3d275b-b3f6-4419-a72a-f6f10f1bef94 + valueUrl: "https://my.portal.com/Task/0d3d275b-b3f6-4419-a72a-f6f10f1bef94" - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id valueCode: myportal-01 - - url: https://fhir.nhs.uk/StructureDefinition/Extension-Linked-Resource - valueReference: - reference: Appointment/067024ee-134c-45fe-aa04-1a8544653c8f 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 - kind: AppointmentBookingInvite status: cancelled statusReason: no-response-within-booking-window - scheduledPeriod: - start: '2025-06-01T09:00:00.000Z' - end: '2025-07-01T09:00:00.000Z' + 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/AppointmentBookingInvite/22dd1b13-6b74-49a2-9fee-89e4a079fdcb + valueUrl: "https://my.portal.com/Task/22dd1b13-6b74-49a2-9fee-89e4a079fdcb" - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id valueCode: myportal-01 appointmentBookingInvitationRejected: @@ -4627,31 +4815,158 @@ components: value: detail: id: c293d1b5-a297-430a-8ffb-7b426854df93 - kind: AppointmentBookingInvite status: rejected - scheduledPeriod: - start: '2025-07-16T09:00:00.000Z' + 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/AppointmentBookingInvite/c293d1b5-a297-430a-8ffb-7b426854df93 + 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 cancelled by the patient due to an improvement in their condition + 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 - kind: AppointmentBookingInvite status: rejected statusReason: condition-resolved - scheduledPeriod: - start: '2025-07-16T09:00:00.000Z' + 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/AppointmentBookingInvite/5d86e89b-53dc-4ed2-b296-bbf31b5333c2 + valueUrl: "https://my.portal.com/Task/5d86e89b-53dc-4ed2-b296-bbf31b5333c2" - url: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id valueCode: myportal-01 - # PIFU + # 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 From 048b1ed5950ca0e6f632a0b0510d9117e6156971 Mon Sep 17 00:00:00 2001 From: Edward Bowyer <285946832+edwardbowyer-nhs@users.noreply.github.com> Date: Tue, 21 Jul 2026 11:54:10 +0100 Subject: [PATCH 10/13] enhance workflow to include short SHA in artifact naming and PR comments and only trigger after an API spec change --- .github/workflows/build-api-spec-html.yml | 27 ++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-api-spec-html.yml b/.github/workflows/build-api-spec-html.yml index 1069a2f..17a6ac2 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: @@ -74,6 +80,25 @@ jobs: - name: Upload API docs 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 the **api-specs-html-docs-${{ steps.short-sha.outputs.value }}** artifact from the workflow run to view the generated docs: + + | Spec | File | + | --- | --- | + | Consumer API | `consumer-api.html` | + | Producer API Standards | `producer-api-standards.html` | + | Record Service API | `record-service-api.html` | From aed2821aacb46b9a05e51200d3c48b261f086b9e Mon Sep 17 00:00:00 2001 From: Edward Bowyer <285946832+edwardbowyer-nhs@users.noreply.github.com> Date: Tue, 21 Jul 2026 12:34:47 +0100 Subject: [PATCH 11/13] Unused file removed --- TASK_RESOURCE_ALIGNMENT_SUMMARY.md | 245 ----------------------------- 1 file changed, 245 deletions(-) delete mode 100644 TASK_RESOURCE_ALIGNMENT_SUMMARY.md diff --git a/TASK_RESOURCE_ALIGNMENT_SUMMARY.md b/TASK_RESOURCE_ALIGNMENT_SUMMARY.md deleted file mode 100644 index 85a10d1..0000000 --- a/TASK_RESOURCE_ALIGNMENT_SUMMARY.md +++ /dev/null @@ -1,245 +0,0 @@ -# Task Resource Alignment Summary - -## Overview -The Consumer spec Task resource has been updated to align with the Producer spec's generic FHIR-based Task implementation. This enables the Task resource to support multiple use cases (questionnaires, appointment booking invites, and future task types) while maintaining backwards compatibility with the existing Questionnaire resource. - -## Why This Change? - -### Previous Implementation -- **Questionnaire-centric**: The Consumer Task resource was essentially a copy of the Questionnaire resource with additional fields for appointment booking invites -- **Limited extensibility**: The `kind` enum was rigid and required updates for each new task type -- **Misaligned with Producer spec**: The Consumer spec Task didn't follow the producer-side FHIR Task pattern -- **Redundancy**: Similar fields and logic across Questionnaire and Task resources - -### New Implementation -- **Generic task framework**: Task resource can represent any patient action (questionnaires, booking invites, etc.) -- **FHIR R4 aligned**: Follows standard FHIR Task structure with fields like `status`, `intent`, `reasonCode`, `reasonReference` -- **Producer-spec aligned**: Matches the Producer API standards for consistency across the aggregator ecosystem -- **Future-proof**: Extensible via `reasonCode` and extensions for new task types -- **Cleaner architecture**: Single generic Task resource instead of type-specific variants - -## Key Changes - -### Removed Fields -- **`kind`** → Replaced by `reasonCode` (provides more semantic meaning) -- **`scheduledPeriod`** → Replaced by `restriction.period` (FHIR standard) -- **`performer`** → Replaced by `owner` (FHIR standard terminology) - -### Added Fields -| Field | Type | Required | Purpose | -|-------|------|----------|---------| -| `id` | string | Yes | Globally unique identifier for the task | -| `identifier` | object | No | System-specific identifier (portal database ID) | -| `intent` | string | Yes | Always "plan" - indicates task intent | -| `authored` | date-time | Yes | When task became available to patient | -| `lastModified` | date-time | No | When task was last modified by patient | -| `restriction.period` | object | No | Start/end dates for task deadline | -| `focus` | object | No | Reference to linked Appointment (if applicable) | -| `for` | object | Yes | Patient identifier (NHS number) | -| `owner` | object | Yes | Responsible organization (provider) | -| `basedOn` | array | No | Optional reference to care pathway | -| `reasonCode` | object | Yes | Codes and text for task type classification | -| `reasonReference` | object | Yes | Reference to Questionnaire or AppointmentBooking | - -### Modified Fields -- **`status`**: Changed from `["not-started", "in-progress", "completed", "cancelled"]` to FHIR-compliant `["requested", "rejected", "cancelled", "in-progress", "completed"]` -- **`statusReason`**: Now structured as codeable concept (ready for future expansion) -- **`description`**: Enhanced with clearer guidance for both questionnaires and invites -- **`extension`**: Streamlined to include Portal Link, Client ID, and Treatment Function (for PIFU only) - -## Task Type Classification - -### Using `reasonCode` to Distinguish Task Types - -The new `reasonCode` structure replaces the old `kind` enum and provides semantic clarity: - -#### For Questionnaires: -```yaml -reasonCode: - coding: - - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" - code: "pifu-triage" # or other questionnaire codes - display: "PIFU Triage Questionnaire" - text: "Patient Initiated Follow-Up Questionnaire" -``` - -#### For Appointment Booking Invites: -```yaml -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" -``` - -## Backwards Compatibility - -### Questionnaire Resource Preserved -- The existing `Questionnaire` resource remains **unchanged** -- Current consumers can continue using the Questionnaire resource without modification -- No breaking changes to the Questionnaire schema - -### Migration Path -1. **Phase 1 (Current)**: Both Task and Questionnaire resources available -2. **Phase 2 (Future)**: Clients should migrate to using Task for new questionnaire implementations -3. **Phase 3 (Future)**: Questionnaire resource may be deprecated (with advance notice) - -## Data Models - -### Appointment Booking Invite (Task) -```yaml -id: ad8baee0-f2b2-4258-ad25-a8de19c32c14 -status: requested -intent: plan -description: Book your Dermatology appointment -authored: '2025-07-16T09:00:00.000Z' -reasonCode: - coding: - - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" - code: "appointment-booking-invite" - text: "Invitation to book an appointment" -reasonReference: - type: AppointmentBooking - reference: "https://my.portal.com/AppointmentBooking/ad8baee0-f2b2-4258-ad25-a8de19c32c14" -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" -``` - -### Questionnaire (Task) -```yaml -id: c21417eb-ffef-4a9e-b367-ebd8b8c29e7c -status: requested -intent: plan -description: Dermatology PIFU follow-up questionnaire -authored: '2025-06-20T18:00:00.000Z' -reasonCode: - coding: - - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type" - code: "pifu-triage" - 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-Task-TreatmentFunction" - valueCoding: - system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" - code: "330" - display: "Dermatology" -``` - -## Examples Updated - -### Appointment Booking Invites (6 examples) -1. ✅ Basic invitation (not started) -2. ✅ With expiry date (requested, not started) -3. ✅ Started but incomplete (in-progress) -4. ✅ Completed (with linked appointment) -5. ✅ Cancelled (no response within booking window) -6. ✅ Rejected (patient condition resolved) - -### Questionnaires (2 new examples) -1. ✅ PIFU questionnaire (with treatment function extension) -2. ✅ Pre-assessment questionnaire (linked to appointment) - -## Implementation Notes - -### For Consumer API Users -- **No immediate changes required** if using Questionnaire resource -- **Optional migration**: Adopt Task resource for future questionnaire implementations -- **New integrations**: Use Task resource for all task types - -### For Portal Providers (Producer API) -- **Already implemented**: Producer spec Task resource remains unchanged -- **Consistency**: Consumer spec now aligns with Producer spec -- **Contract testing**: Ensure portal systems work with both old Questionnaire and new Task patterns during transition - -### For the Aggregator Service -- **Data mapping**: When aggregating from portals, map incoming Task data to both Questionnaire (for backwards compatibility) and Task resources -- **Gradual rollout**: Transition consumers to Task resource over time -- **Validation**: Ensure both resourceType patterns are properly validated - -## Status Values Mapping - -| Old (Questionnaire) | New (Task) | Meaning | -|-------------------|-----------|---------| -| `not-started` | `requested` | Task available but not yet started | -| `in-progress` | `in-progress` | Task started by patient | -| `completed` | `completed` | Task finished by patient | -| `cancelled` | `cancelled` | Task cancelled by system or patient | -| (new) | `rejected` | Patient explicitly declined task | - -## Extension Framework - -The streamlined extensions provide: - -1. **Portal Link** (required) - - Deep link to patient-facing portal interface - - System: `https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link` - -2. **Client ID** (optional) - - Upstream system identifier - - System: `https://fhir.nhs.uk/StructureDefinition/Extension-Client-id` - -3. **Treatment Function** (conditional) - - For PIFU questionnaires only - - System: `https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction` - -## Future Enhancements - -The new Task structure enables: -- ✅ Appointment booking invites -- ✅ Pre-assessment questionnaires -- ✅ PIFU questionnaires -- 🔄 Referral action tasks (future) -- 🔄 Document review tasks (future) -- 🔄 Custom patient tasks (extensible via reasonCode) - -## Migration Checklist - -For NHS App and Consumer Implementations: -- [ ] Review and test new Task examples -- [ ] Update data models to support new fields (`intent`, `reasonCode`, `reasonReference`, `for`, `owner`) -- [ ] Implement logic to handle `reasonCode.system` for task type differentiation -- [ ] Handle optional fields appropriately (e.g., `focus` for incomplete booking invites) -- [ ] Add support for `statusReason` for rejection details -- [ ] Test rendering of both questionnaire and appointment booking tasks -- [ ] Maintain Questionnaire resource support during transition period -- [ ] Plan migration strategy for existing questionnaire implementations - -## Questions & Clarifications - -**Q: When will the Questionnaire resource be deprecated?** -A: No immediate deprecation. The Questionnaire resource will remain supported during a transition period (to be determined). We'll provide advance notice before any deprecation. - -**Q: Do I need to update my system immediately?** -A: No. Existing implementations using Questionnaire continue to work. Adopt Task resource for new implementations or when ready to migrate. - -**Q: How do I distinguish between task types?** -A: Use the `reasonCode.coding.system` field: -- Questionnaires: `Extension-Questionnaire-Type` -- Booking invites: `Extension-Task-Type` - -**Q: What about linked appointments?** -A: Use the `focus` field to reference an appointment: -- For completed booking invites: `focus.reference` points to the booked appointment -- For questionnaires before appointment: `focus` may be empty or optional - -**Q: Can I store custom data in Task?** -A: Yes, use extensions (array) to add custom fields following FHIR extension patterns. - ---- - -**Document Version**: 1.0 -**Last Updated**: 2026-07-20 -**Status**: Implementation Complete From 8dc8f5a02e39d6fc8fb1576bb514525e23eb9b2f Mon Sep 17 00:00:00 2001 From: Edward Bowyer <285946832+edwardbowyer-nhs@users.noreply.github.com> Date: Tue, 21 Jul 2026 12:38:56 +0100 Subject: [PATCH 12/13] Added link to download artificat directly from PR --- .github/workflows/build-api-spec-html.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.github/workflows/build-api-spec-html.yml b/.github/workflows/build-api-spec-html.yml index 17a6ac2..ff6006e 100644 --- a/.github/workflows/build-api-spec-html.yml +++ b/.github/workflows/build-api-spec-html.yml @@ -95,10 +95,4 @@ jobs: Built from commit `${{ steps.short-sha.outputs.value }}` — [view workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - Download the **api-specs-html-docs-${{ steps.short-sha.outputs.value }}** artifact from the workflow run to view the generated docs: - - | Spec | File | - | --- | --- | - | Consumer API | `consumer-api.html` | - | Producer API Standards | `producer-api-standards.html` | - | Record Service API | `record-service-api.html` | + **Download artifact:** [api-specs-html-docs-${{ steps.short-sha.outputs.value }}.zip](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/attempts/1#artifacts) \ No newline at end of file From 59d8e4c7ad2e23845ca109a4e9c080da21ac9ebf Mon Sep 17 00:00:00 2001 From: Edward Bowyer <285946832+edwardbowyer-nhs@users.noreply.github.com> Date: Tue, 21 Jul 2026 12:48:24 +0100 Subject: [PATCH 13/13] Update comment to direclty link to download --- .github/workflows/build-api-spec-html.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-api-spec-html.yml b/.github/workflows/build-api-spec-html.yml index ff6006e..d8b2ac3 100644 --- a/.github/workflows/build-api-spec-html.yml +++ b/.github/workflows/build-api-spec-html.yml @@ -78,6 +78,7 @@ jobs: - name: Upload API docs artifact + id: upload-artifact uses: actions/upload-artifact@v4 with: name: api-specs-html-docs-${{ steps.short-sha.outputs.value }} @@ -95,4 +96,4 @@ jobs: Built from commit `${{ steps.short-sha.outputs.value }}` — [view workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - **Download artifact:** [api-specs-html-docs-${{ steps.short-sha.outputs.value }}.zip](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}/attempts/1#artifacts) \ No newline at end of file + **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