Health New Zealand Te Whatu Ora Shared Care FHIR API
0.4.1 - release New Zealand flag

Health New Zealand Te Whatu Ora Shared Care FHIR API - Local Development build (v0.4.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Outreach Use Cases

The following examples show the expected interactions for creating and fulfilling outreach referrals. The examples mention some of the details used for immunisation outreach between AIR and Whaihua, but the outreach process is intended as a general workflow process.

Key elements that need to be updated / added at each step are shown in the tables describing key steps.

1. Create outreach referral

Creating Outreach referral ServiceRequestCreating Outreach referral ServiceRequestOutreach Referral FHIR ServerPlacer (Health service)Outreach Referral FHIR ServerNEMSFiller (Outreach provider)Placer (Health service)Placer (Health service)Outreach Referral FHIR ServerOutreach Referral FHIR ServerNEMSNEMSFiller (Outreach provider)Filler (Outreach provider)Outreach Referral FHIR Server[01]Create ServiceRequest for outreach[02]Success[03]Publish ServiceRequest created event[04]Notify


[01] Create ServiceRequest for outreach

Element Expected update/information
ServiceRequest.status create as 'active' code
ServiceRequest.intent create as 'plan' code
ServiceRequest.code use code describing type of outreach (e.g. 'Immunization' code for ism)
ServiceRequest.subject set to NHI identifier for patient
ServiceRequest.priority 'routine'
ServiceRequest.requester requester to reference describing service (e.g. Logical id using system "https://hub.services.digital.health.nz/ns/hip-application-id" and the digital services hub application ID)
ServiceRequest.meta.source update to to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

2. Accept outreach referral

Accepting Outreach referral ServiceRequestAccepting Outreach referral ServiceRequestOutreach Referral FHIR ServerPlacer (Health service)Outreach Referral FHIR ServerNEMSFiller (Outreach provider)Placer (Health service)Placer (Health service)Outreach Referral FHIR ServerOutreach Referral FHIR ServerNEMSNEMSFiller (Outreach provider)Filler (Outreach provider)Outreach Referral FHIR Server[04]Notify[05]Retrieve ServiceRequest to work on[06]Update ServiceRequest to claim[07]Success[08]Publish ServiceRequest updated event[09]Notify


[06] Update ServiceRequest to claim

Element Expected update/information
ServiceRequest.performer update performer to reference describing service (e.g. Logical id using system "https://hub.services.digital.health.nz/ns/hip-application-id" and the digital services hub application ID)
ServiceRequest.locationReference update to outreach provider location reference (HPI-F if available, otherwise Facility Name)
ServiceRequest.meta.source update to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

3. Create Tasks to track outreach activities

Creating TaskCreating TaskOutreach Referral FHIR ServerPlacer (Health service)Outreach Referral FHIR ServerNEMSFiller (Outreach provider)Placer (Health service)Placer (Health service)Outreach Referral FHIR ServerOutreach Referral FHIR ServerNEMSNEMSFiller (Outreach provider)Filler (Outreach provider)Outreach Referral FHIR Server[10]Create outreach fulfilment Task[11]Outreach activities[12]Update Task[13]success


[10] Create outreach fulfilment Task

Element Expected update/information
Task.status 'accepted' to indicate has agreed to do it but work hasn't started on it
Task.basedOn Reference to the ServiceRequest this Task is related to
Task.intent 'plan'
Task.code code describing the type of task (e.g. for Whaihua doing AIR outreach, a general 'Immunization' code will be used initially)
Task.for NHI identifier for patient
Task.priority 'routine'
Task.input reference to ImmunizationRec in AIR
Task.meta.source update to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

[12] Update Task

Element Expected update/information
Task.status 'in-progress' to indicate work has started on it
Task.meta.source update to whaihua to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

4. Create and store Communications against ServiceRequests

Creating and storing Communications against ServiceRequestCreating and storing Communications against ServiceRequestOutreach Referral FHIR ServerPlacer (Health service)Outreach Referral FHIR ServerNEMSFiller (Outreach provider)Placer (Health service)Placer (Health service)Outreach Referral FHIR ServerOutreach Referral FHIR ServerNEMSNEMSFiller (Outreach provider)Filler (Outreach provider)Outreach Referral FHIR Server[14]Create Communication[15]Update ServiceRequest[16]Publish ServiceRequest updated event[17]Success[18]Notify


[14] Create Communication

Element Expected update/information
Communication.subject Patient NHI reference
Communication.status 'completed'
Communication.basedOn Reference to related ServiceRequest
Communication.extension.communicationContactPoint ContactPoint used for communication
Communication.sent date sent
Communication.recipient Reference to patient?
Communication.received when received (if relevant)
Communication.payload Message content (if relevant)
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

[15] Update ServiceRequest

Element Expected update/information
ServiceRequest.supportingInfo Reference to Communication created in [14]
ServiceRequest.meta.source update to whaihua to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

5. Revoke/cancel an outreach referral

Cancel outreach ReferralCancel outreach ReferralOutreach Referral FHIR ServerOutreach Referral FHIR ServerPlacer (Health service)Outreach Referral FHIR ServerNEMSFiller (Outreach provider)Placer (Health service)Placer (Health service)Outreach Referral FHIR ServerOutreach Referral FHIR ServerNEMSNEMSFiller (Outreach provider)Filler (Outreach provider)Outreach Referral FHIR ServerOutreach Referral FHIR Server[19]Update outreach referral ServiceRequest to cancel[20]Create ServiceRequest update event[21]Success[22]Notify[23]Close open Task(s)[24]Success


[18] Update outreach referral ServiceRequest to cancel (or complete from Placer side)

Element Expected update/information
ServiceRequest.status 'revoked' or 'completed'
ServiceRequest.extension.statusReason update to reflect reason for current status [codes TBC]
ServiceRequest.meta.source update to ism to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

[22] Close open Task(s)

Element Expected update/information
Task.status 'cancelled'
ServiceRequest.meta.source update to whaihua to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

6. Complete and close outreach referral

Complete outreach ReferralComplete outreach ReferralOutreach Referral FHIR ServerOutreach Referral FHIR ServerPlacer (Health service)Outreach Referral FHIR ServerNEMSFiller (Outreach provider)Placer (Health service)Placer (Health service)Outreach Referral FHIR ServerOutreach Referral FHIR ServerNEMSNEMSFiller (Outreach provider)Filler (Outreach provider)Outreach Referral FHIR ServerOutreach Referral FHIR Server[25]Update outstanding Task(s) to completed[26]Success[27]Update outreach ServiceRequest to completed[28]Publish ServiceRequest completed event[29]success[30]Notify


[25] Update outstanding Task(s) to completed

Element Expected update/information
Task.status 'Completed'
Task.meta.source update to whaihua to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

[27] Update outreach referral ServiceRequest to complete

Element Expected update/information
ServiceRequest.status 'completed'
ServiceRequest.extension.statusReason update to reflect reason for current status [codes TBC]
ServiceRequest.meta.source update to whaihua to indicate who edited it last
ServiceRequest.meta.tag.system use 'https://hub.services.digital.health.nz/ns/correlation-id' for the correlation id system
ServiceRequest.meta.tag.code the correlationId uuid gets added here, this gets passed on to the the event in NEMS

7. Find existing outreach information for a patient

[Requirements TBC]