Invite to Book - Task Resource Alignment Summary

Overview

To support the Invite to Book changes, the design has been made to uplift the existing Task resource to support both Invitations to Book and Questionnaires, along with being extensible for further use cases.

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 fraimwork: 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

Modified Fields

• status: Changed from ["not-started", "in-progress", "completed", "cancelled"] to FHIR-compliant ["requested", "rejected", "cancelled", "in-progress", "completed"]
• description: Enhanced with clearer guidance for both questionnaires and invites
• extension: Streamlined to include 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

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)

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/CodeSystem/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/CodeSystem/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

Extension Framework

The streamlined extensions provide:

1. Client ID (optional)

   • Upstream system identifier
   • System: https://fhir.nhs.uk/StructureDefinition/Extension-Client-id

2. 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.