diff --git a/specification/patient-care-aggregator-api-consumer-api.yaml b/specification/patient-care-aggregator-api-consumer-api.yaml index b669ffa..8e7ce0e 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 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: + 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 @@ -1394,8 +1625,10 @@ components: $ref: "#/components/examples/allAppointmentStates" allDocumentStates: $ref: "#/components/examples/allDocumentStates" - allQuestionnairestates: - $ref: "#/components/examples/allQuestionnairestates" + allQuestionnaireStates: + $ref: "#/components/examples/allQuestionnaireStates" + allAppointmentBookingInvitationStates: + $ref: "#/components/examples/allAppointmentBookingInvitationStates" incompleteWaitingLists: $ref: "#/components/examples/incompleteWaitingLists" incompleteWaitingListBreastScreening: # Not current supported @@ -1540,7 +1773,7 @@ components: $ref: "#/components/examples/correspondenceReadUnlinked" #Attachment: # $ref: "#/components/examples/Attachment" - # Questionnaires + # Task - Questionnaires questionnaireIncompleteLinked: $ref: "#/components/examples/questionnaireIncompleteLinked" questionnaireIncompleteUnlinked: @@ -1553,6 +1786,21 @@ components: $ref: "#/components/examples/questionnaireCompleteLinked" questionnaireCompleteUnlinked: $ref: "#/components/examples/questionnaireCompleteUnlinked" + # Task - Appointment Booking Invitations + appointmentBookingInvitation: + $ref: "#/components/examples/appointmentBookingInvitation" + appointmentBookingInvitationWithExpiryDate: + $ref: "#/components/examples/appointmentBookingInvitationWithExpiryDate" + appointmentBookingInvitationStartedNotComplete: + $ref: "#/components/examples/appointmentBookingInvitationStartedNotComplete" + appointmentBookingInvitationCompleted: + $ref: "#/components/examples/appointmentBookingInvitationCompleted" + appointmentBookingInvitationCancelledNoResponse: + $ref: "#/components/examples/appointmentBookingInvitationCancelledNoResponse" + appointmentBookingInvitationRejected: + $ref: "#/components/examples/appointmentBookingInvitationRejected" + appointmentBookingInvitationRejectedConditionResolved: + $ref: "#/components/examples/appointmentBookingInvitationRejectedConditionResolved" # PIFU pifuZeroWaitingListZeroPifu: $ref: "#/components/examples/pifuZeroWaitingListZeroPifu" @@ -1867,7 +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 @@ -1900,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: | @@ -4269,6 +4551,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 diff --git a/specification/patient-care-aggregator-api-producer-api-standards.yaml b/specification/patient-care-aggregator-api-producer-api-standards.yaml index d81497b..af3c9b3 100644 --- a/specification/patient-care-aggregator-api-producer-api-standards.yaml +++ b/specification/patient-care-aggregator-api-producer-api-standards.yaml @@ -242,12 +242,12 @@ paths: operationId: get-tasks description: | ## Overview - This endpoint returns a list of tasks for completion of questionnaires from a secondary care booking system for a given patient. + This endpoint returns a list of tasks, such as those for appointment booking invitations or for the completion of questionnaires, from a secondary care booking system for a given patient. It returns the tasks as a FHIR 'Bundle' containing FHIR 'Task' resources. Note that the above URL path is an example - you can use a different URL path if you prefer. - ## Questionnaires inclusion and exclusion rules + ## Task inclusion and exclusion rules The endpoint includes / excludes tasks as per the following rules: - NHS in England only: Only include tasks related to appointments for care settings within the NHS in England. - NHS Trusts only: Only include tasks related to appointments for acute, mental health or community care settings - not any other type. @@ -289,7 +289,7 @@ paths: # - $ref: "#/components/parameters/nhsdTargetIdentifier" responses: 2XX: - $ref: "#/components/responses/questionnaireHappyPath" + $ref: "#/components/responses/tasksHappyPath" 4XX: $ref: "#/components/responses/4XX" components: @@ -1052,7 +1052,7 @@ components: description: The Portal provider deep link URL. If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. example: "https://my.portal.com/Document/b710e648-c12e-4f66-80e2-9957a254900f" Task: - description: "FHIR TASK resource for the questionnaire" + description: "FHIR Task resource for the task" type: object required: - resourceType @@ -1063,7 +1063,7 @@ components: - for - authored - reasonReference - - owner + # removed 'owner' as it might need to be optional, as booking invites might offer a range of hospitals to choose from - reasonCode properties: resourceType: @@ -1091,7 +1091,7 @@ components: type: string example: "3a146c43-2b21-44e9-95bc-6f4849e504c8" basedOn: - description: Reference to the related CarePlan (Pathway). This reference should contain the pathway ID. This field is required for PIFU questionnaires to identify duplicate entries and is optional for other questionnaire types. + description: Reference to the related CarePlan (Pathway). This reference should contain the pathway ID. This field is required to identify duplicate entries and is optional for other task types. type: array minItems: 0 maxItems: 1 @@ -1124,25 +1124,55 @@ components: description: "Care pathway Identifier" example: "RBH5644312231" status: - description: "Status of the Task for the completion of the Questionnaire. See: https://build.fhir.org/valueset-task-status.html" + description: "Status of the task. See: https://build.fhir.org/valueset-task-status.html" type: string enum: - requested + # rejected is in FHIR R4, but will need to be added to our spec + - rejected - cancelled - in-progress - completed + statusReason: + # statusReason exists in FHIR R4 but we will need to define which codes can be used + # as it is a CodeableConcept, which allows us to extend it as we see fit + description: "Additional detail about the status of a task, for when further clarity is required, such as the reason a patient rejected an invite to book their appointment." + type: object + properties: + coding: + type: array + minItems: 1 + maxItems: 1 + items: + type: object + properties: + system: + type: string + enum: + - https://fhir.nhs.uk/CodeSystem/Task-StatusReason + code: + type: string + enum: + # This a just some possible codes; need more input for stakeholders to determine suitable list + - appointment-type-unsuitable + - condition-resolved + - location-unsuitable + - no-reason-given + - no-response-within-booking-window intent: description: "Hardcoded to plan. See: https://build.fhir.org/valueset-task-intent.html" type: string enum: - plan description: - description: "The patient-friendly, standardised title of the questionnaire that is suitable for display to patients. This value should match the name shown in your own interface and should follow the structure {Specialty name} {Questionnaire type}. If the questionnaire is linked to an appointment, the specialty should align with that appointment. For Patient Initiated Follow-Up (PIFU) questionnaires, the questionnaire type should not be included. The values presented within this field are required to be provided for Data Quality Assurance." + # Might need to extend this description to mention appointment bookings + description: "The patient-friendly, standardised title of the task that is suitable for display to patients. For questionnaires this value should match the name shown in your own interface and should follow the structure {Specialty name} {Questionnaire type}. If the questionnaire is linked to an appointment, the specialty should align with that appointment. For Patient Initiated Follow-Up (PIFU) questionnaires, the questionnaire type should not be included. The values presented within this field are required to be provided for Data Quality Assurance." type: string example: Dermatology pre-assessment questionnaire focus: + # This is optional and wouldn't apply to invites, as the appointment wouldn't exist type: object - description: Appointment reference to the appointments this questionnaire relates to. + description: Appointment reference to the appointments this task relates to (optional). Not required for appointment booking invites. required: - type - reference @@ -1158,7 +1188,7 @@ components: example: https://my.portal.com/fhir/R4/Appointment/ec2458f2-1e24-41c8-b71b-0e701af7583d for: type: object - description: Patient whom the questionnaire relates to. + description: Patient whom the task relates to. required: - type - identifier @@ -1185,40 +1215,47 @@ components: example: "9123456789" authored: type: string - description: Date the questionnaire was first made available to a patient in a UTC format. + description: Date the task was first made available to a patient in a UTC format. example: "2021-06-13T12:30:00+00:00" lastModified: type: string - description: Records the date and time (UTC) the questionnaire was completed by the patient. For Patient Initiated Follow-up (PIFU) feature, this field represents the date and time the patient last requested a follow-up appointment, and applies only to that individual PIFU request. This date must be greater than or equal to authored date. + description: Records the date and time (UTC) the task was completed by the patient. For Patient Initiated Follow-up (PIFU) feature, this field represents the date and time the patient last requested a follow-up appointment, and applies only to that individual PIFU request. This date must be greater than or equal to authored date. example: "2025-08-28T12:30:00+00:00" restriction: + # This is optional, but can be used for invites to signal when it must be actioned by type: object - description: Constraints on the questionnaire. + description: Constraints on the task. properties: period: type: object properties: end: type: string - description: Indicates the end date for the questionnaire. For the Patient Initiated Follow-up (PIFU) feature, this represents the expiration date of the questionnaire. After this date has passed, the patient can no longer raise a follow-up request. + description: Indicates the end date for the task. For the Patient Initiated Follow-up (PIFU) feature, this represents the expiration date of the questionnaire. After this date has passed, the patient can no longer raise a follow-up request. For appointment booking invites, this date is when this invite expires. example: "2025-10-18T12:30:00+00:00" reasonReference: + # This mandatory, so its type enum will need to be extended to include invites + # Not sure why it is called "reasonReference"; doesn't seem like a suitable name to me type: object - description: Reference to the Questionnaire being requested. + description: Reference to the Task being requested. required: - type - reference properties: type: type: string - description: Questionnaire FHIR Resource + description: FHIR Resource enum: - "Questionnaire" + # Need to check if this should relate to the specific task, such as Invite to Book, or just be "Task" + - "AppointmentBooking" reference: type: string description: The Portal provider deep link URL. If the provider is sending MI events to the Wayfinder Reporting Service API then the tracking id may need to be appended to the deep link URL. Refer to guidance at the beginning of the specification - Patient Care Aggregator Reporting Service API considerations. example: "https://my.portal.com/Questionnaire/3a146c43-2b21-44e9-95bc-6f4849e504c8" owner: + # This might be a problem as it is mandatory, and for invite to book the patient + # would likely be given the choice of hospitals at which to have their appointment type: object description: Organization responsible for the patients care required: @@ -1249,15 +1286,16 @@ components: type: string example: Barnsley Hospital NHS Foundation Trust reasonCode: + # This is mandatory, so will need to be extended to include booking invites type: object - description: Reason for the Task, the request for a patient to complete a Questionnaire. + description: Reason for the Task, the request for a patient to complete a the Task. required: - coding - text properties: coding: type: object - description: Array of Coding for the type of questionnaire to be completed. + description: Array of Coding for the type of task to be completed. required: - system - code @@ -1265,27 +1303,29 @@ components: properties: system: type: string - description: URI to identifier Questionnaire types + description: URI to identify Task types enum: - https://fhir.nhs.uk/StructureDefinition/Extension-Questionnaire-Type + # Proposed extension; should it be for a generic task or for an invite? + - https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type code: type: string - description: Questionnaire type code. For questionnaires that are part of the patient initiated follow-up (PIFU) feature, the questionnaire type code must be set to "pifu-triage". + description: Task type code. For questionnaires that are part of the patient initiated follow-up (PIFU) feature, the questionnaire type code must be set to "pifu-triage". example: CONS-Survey display: type: string - description: Questionnaire type + description: Task type example: Consultation Survey text: type: string - description: Questionnaire type + description: Task type example: Pre-consultation Survey extension: description: "FHIR extensions for Task resources." type: array items: anyOf: - - description: "Treatment function associated to the Questionnaire. Please note: this must be provided for any \"pifu-triage\" Questionnaires." + - description: "Treatment function associated to the Task. Please note: this must be provided for any \"pifu-triage\" Questionnaires." type: object required: - url @@ -1470,7 +1510,7 @@ components: $ref: "#/components/examples/emptyBundle" document: $ref: "#/components/examples/document" - questionnaireHappyPath: + tasksHappyPath: description: A successful request. headers: #X-Request-ID: @@ -1485,7 +1525,9 @@ components: emptyBundle: $ref: "#/components/examples/emptyBundle" questionnaire: - $ref: "#/components/examples/questionnaire" + $ref: "#/components/examples/taskQuestionnaire" + appointmentBookingInvite: + $ref: "#/components/examples/taskAppointmentBookingInvite" 4XX: description: | When the service is unable to serve a successful response a FHIR `OperationOutcome` resource should be returned with the relevant HTTP status code defined as follows: @@ -1769,7 +1811,7 @@ components: - attachment: contentType: "application/pdf" url: "https://my.portal.com/Document/2f02f7ac-0de5-4271-81ad-92b69ead27e9" - questionnaire: + taskQuestionnaire: summary: 200 Example Patient with a Questionnaire value: resourceType: Bundle @@ -1820,6 +1862,57 @@ components: system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" code: "330" display: "Dermatology" + taskAppointmentBookingInvite: + summary: 200 Example Patient with a Appointment Booking Invitation + value: + resourceType: Bundle + type: searchset + total: 1 + entry: + - fullUrl: "https://my.patientportal.co.uk/Task/3947e645-c7f9-4791-b5b5-386b97e4b271" + search: + mode: match + resource: + resourceType: Task + id: "6383658e-fef4-4b89-9f68-7af67ed8c382" + basedOn: + - type: "CarePlan" + identifier: + system: "https://fhir.nhs.uk/Id/PathwayId" + value: "RBH5644312231" + status: "requested" + intent: "plan" + description: "Invitation to Book a Video Consultation Appointment" + for: + type: "Patient" + identifier: + system: "https://fhir.nhs.uk/Id/nhs-number" + value: "9000000014" + authoredOn: "2026-07-13T12:30:00+00:00" + restriction: + period: + end: "2026-07-13T18:00:00+00:00" + reasonReference: + type: "AppointmentBooking" + reference: "https://my.portal.com/AppointmentBooking/cdb83383-f17e-4bf7-8f40-342f7f7c7d8d" + owner: + type: "Organization" + identifier: + system: "https://fhir.nhs.uk/Id/ods-organization-code" + value: "RFF" + display: "Barnsley Hospital NHS Foundation Trust" + reasonCode: + coding: + - system: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-Type" + code: "VIDEO-CONSULT" + display: "Video Consultation" + text: "Online Video Consultation" + extension: + - url: "https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction" + valueCoding: + system: "https://fhir.nhs.uk/CodeSystem/Specialty-1" + code: "330" + display: "Dermatology" missingNhsNumber: summary: 400 Missing patient:identifier search parameter description: No patient:identifier as a search parameter.