SPEC CHANGE - WPP-11130 - Proposed changes to API specs for Invite to Book by simeonparris-nhs · Pull Request #166 · NHSDigital/patient-care-aggregator-api

simeonparris-nhs · 2026-07-16T13:51:17Z

Invite to Book - 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 (FHIR standard, 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:

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:

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

Phase 1 (Current): Both Task and Questionnaire resources available
Phase 2 (Future): Clients should migrate to using Task for new questionnaire implementations
Phase 3 (Future): Questionnaire resource may be deprecated (with advance notice)

Data Models

Appointment Booking Invite (Task)

id: ad8baee0-f2b2-4258-ad25-a8de19c32c14
status: requested
intent: plan
description: Book your Dermatology appointment
authored: '2026-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"
restriction:
  repetitions: 1
  period:
    start: '2026-07-16T09:00:00.000Z'
    end: '2026-08-16T23:59:59.000Z'

Questionnaire (Task)

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"

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:

Portal Link (required)
- Deep link to patient-facing portal interface
- System: https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link
Client ID (optional)
- Upstream system identifier
- System: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id
Treatment Function (conditional)
- For PIFU questionnaires only
- System: https://fhir.nhs.uk/StructureDefinition/Extension-Task-TreatmentFunction

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.

so that it is suitable for a variety of tasks rather than just questionnaire responses

so that a variety of task details, such as booking invites and questionnaire responses can be communicated

…r-ItB

for allAppointmentBookingInvitationStates

…hile backwards compatible

RavenDuffyNHS · 2026-07-21T08:22:37Z

Just want to check this has been aligned with kevin/sachit?

edwardbowyer-nhs · 2026-07-21T09:51:41Z

Just want to check this has been aligned with kevin/sachit?

The design has been run through with Sachit yes, we collaborated on that, but not this specific spec change. Reaching out to David Rabbich in Sachit and Kevin's absence.

RavenDuffyNHS · 2026-07-21T10:01:36Z

Just want to check this has been aligned with kevin/sachit?

The design has been run through with Sachit yes, we collaborated on that, but not this specific spec change. Reaching out to David Rabbich in Sachit and Kevin's absence.

Definitely think this will be a positive change as the line between tasks and questionnaires is currently quite blurry.

…nts and only trigger after an API spec change

github-actions · 2026-07-21T11:49:34Z

API Spec HTML Docs

Built from commit a0d3416 — view workflow run

Download HTML API Specs: api-specs-html-docs-a0d3416.zip

edwardbowyer-nhs · 2026-07-22T09:53:10Z

Feedback from David Rabbich (Responses in Italics)

new field "authored" doesn't have a direct reference in the R4 Task object, the closest being "authoredOn". Was this change intentional?
Good spot, I imagine a typo in the initial implementation of the Task resource, maintaing to ensure backwards compatibility.
I noticed the addition of restriction.period as a new field, but wondered if this also meant that you were supporting some of the other fields in "restriction", such as repetitions and recipient? I could see someone submitting repetitions thinking it was supported and then being surprised it had no effect.
As neither of the other fields are related for our two current use cases, decided not to include.
My only other point was around the disparity between supported objects on fields like "for". In the FHIR R4 spec, it supports Any object type, but the spec looks to be only allowing patient. What would happen if I submitted say, an organisation?
Decision to add additionally supported fields when we implement new uses cases to make use of them
Same point as above but for the owner field. It supports multiple objects in R4, but only Organisation under this scheme.
Decision to add additionally supported fields when we implement new uses cases to make use of them

edwardbowyer-nhs · 2026-07-24T10:36:53Z

        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


Expand on inclusion / exclusion rules. Still applicable for generic tasks?

Potentially add, review clinical Monday drop in

edwardbowyer-nhs · 2026-07-24T10:39:26Z

      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.


Be explicit, just ItB and questionnaires. Will extend later

edwardbowyer-nhs · 2026-07-24T10:42:32Z

      responses:
        2XX:
-          $ref: "#/components/responses/questionnaireHappyPath"
+            $ref: "#/components/responses/tasksHappyPath"


Indentation. Task singular?

edwardbowyer-nhs · 2026-07-24T10:43:42Z

                    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"


Expand on Task uses, explicit

edwardbowyer-nhs · 2026-07-24T10:55:55Z

        - authored
        - reasonReference
-        - owner
+        # removed 'owner' as it might need to be optional, as booking invites might offer a range of hospitals to choose from


Revert, will be needed for both.

edwardbowyer-nhs · 2026-07-24T10:59:43Z

              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.


Required for PIFU questionnaires

edwardbowyer-nhs · 2026-07-24T11:03:32Z

                        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"


Expand on link details, description on what each status means etc...

simeonparris-nhs and others added 11 commits July 15, 2026 12:36

modify task resource in producer spec

9073c7d

so that it is suitable for a variety of tasks rather than just questionnaire responses

add task resource to the consumer spec

1a7e6ce

so that a variety of task details, such as booking invites and questionnaire responses can be communicated

Merge branch 'master' into apm-000-WPP-11130-proposed-task-changes-fo…

cb5b9a1

…r-ItB

update producer task overview

7ebc882

add consumer spec task examples

31daaf1

add more examples to consumer spec

2d4f6cf

for allAppointmentBookingInvitationStates

add task examples to producer spec

0916cbf

correct producer spec task response

8d7513c

correct spelling of allQuestionnaireStates in consumer spec

986cb75

Aligned Task consumer spec more closely with Producer spec, generic w…

44e6d2b

…hile backwards compatible

Merged aligned Consumer Task resource with Producer

8a7a520

edwardbowyer-nhs changed the title ~~DRAFT - WPP-11130 - Proposed changes to API specs for Invite to Book~~ DRAFT - SPEC CHANGE - WPP-11130 - Proposed changes to API specs for Invite to Book Jul 20, 2026

NHSDigital deleted a comment from github-actions Bot Jul 21, 2026

edwardbowyer-nhs added 4 commits July 21, 2026 11:54

enhance workflow to include short SHA in artifact naming and PR comme…

048b1ed

…nts and only trigger after an API spec change

Merge

a58c410

Unused file removed

aed2821

Added link to download artificat directly from PR

8dc8f5a

NHSDigital deleted a comment from github-actions Bot Jul 21, 2026

Update comment to direclty link to download

59d8e4c

edwardbowyer-nhs changed the title ~~DRAFT - SPEC CHANGE - WPP-11130 - Proposed changes to API specs for Invite to Book~~ SPEC CHANGE - WPP-11130 - Proposed changes to API specs for Invite to Book Jul 22, 2026

NHSDigital deleted a comment from github-actions Bot Jul 22, 2026

edwardbowyer-nhs reviewed Jul 24, 2026

View reviewed changes

Uh oh!

Conversation

simeonparris-nhs commented Jul 16, 2026 • edited by edwardbowyer-nhs Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Invite to Book - Task Resource Alignment Summary

Overview

Why This Change?

Previous Implementation

New Implementation

Key Changes

Removed Fields

Added Fields

Modified Fields

Task Type Classification

Using reasonCode to Distinguish Task Types

For Questionnaires:

For Appointment Booking Invites:

Backwards Compatibility

Questionnaire Resource Preserved

Migration Path

Data Models

Appointment Booking Invite (Task)

Questionnaire (Task)

Implementation Notes

For Consumer API Users

For Portal Providers (Producer API)

For the Aggregator Service

Status Values Mapping

Extension Framework

Questions & Clarifications

Uh oh!

RavenDuffyNHS commented Jul 21, 2026

Uh oh!

edwardbowyer-nhs commented Jul 21, 2026

Uh oh!

RavenDuffyNHS commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026

API Spec HTML Docs

Uh oh!

edwardbowyer-nhs commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

simeonparris-nhs commented Jul 16, 2026 •

edited by edwardbowyer-nhs

Loading

Using `reasonCode` to Distinguish Task Types

edwardbowyer-nhs commented Jul 22, 2026 •

edited

Loading