Process message

Owned by Andrew Turner (Unlicensed)
Last updated: Aug 19, 2024 by Daniel Whiteley
2 min read

[Prod Resource]

https://www.hl7.org/fhir/STU3/operationdefinition.html

https://www.hl7.org/fhir/STU3/operations.html

description

Please note: this operation is not to be confused with the FHIR-defined $process-message. The two operations have different syntax and behaviour.

This operation allows:

  • a System user to create or update a Patient

Accepts a single FHIR Patient resource. Steps of processing:

  • If the patient does not already exist on PKB, a record will be created for them.

  • If the patient does already exist on PKB, their demographics will be updated.

  • If an email is included in the Patient resource, an invitation may be sent. Note that only one email address will be processed if more than one are provided.

  • Use of the team alias extension allows a patient to be added to specified teams. Multiple instances of the extension may be included to add the patient to multiple teams. If the team alias extension is included, then there must be an instance which includes the alias for the configured default team of the sending organisation.

  • If the team alias extension is not included in a Patient resource, the patient will be added to the configured default team of the sending organisation.

Authorisation and authentication

In addition to the OAuth 2.0 access token, the X-Org-Public-Id HTTP header must be provided in the request to specify the organisation that the system is calling on behalf of. The parameter will be the UUID of the PKB organisation.

Mappings

PKB

FHIR

Notes

[[User.Public ID]]

N/A - cannot be set with this endpoint.

 

[[User.Title]]

Patient.name.prefix[0]

 

[[User.Given Name]]

Patient.name.given[0]

Required

[[User.Family Name]]

Patient.name.family

Required

[[Patient.Middle Names]]

Patient.name.given[1-x]

 All individual elements will be delimited by a single token of whitespace

[[Patient.Address Line 1]]

Patient.address.line[0]

 

[[Patient.Address Line 2]]

Patient.address.line[1]

 

[[Patient.City]]

Patient.address.city

 

[[Patient.State]]

Patient.address.state

 

[[Patient.Country]]

Patient.address.country

 

[[Patient.Postal Code]]

Patient.address.postalCode

 

[[Patient.Date of Birth]]

Patient.birthDate

Required

[[Patient.Death Timestamp]]

Patient.deceasedDateTime

OR

Patient.deceasedBoolean

Either is accepted.

[[Patient.Gender]]

Patient.gender

Required

[[Patient.Language]]

This will determine the language that the PKB GUI displays in following logon for the patient. If no language is provided, the GUI will display in a default language.

The language code value is a two digit language code, e.g. “en”.

[[Patient.Time Zone]]

N/A - cannot be set with this endpoint.

 

[[Patient.Phone]]

  • Patient.telecom[x]: ContactPoint

    • system = phone

    • value = [[Patient.Phone]]

 

[[Patient.Status]]

N/A - cannot be set with this endpoint.

 

[[Patient.Registered]]

N/A - cannot be set with this endpoint.

 

[[Patient.Sharing Disabled]]

N/A - cannot be set with this endpoint.

 

[[Patient.Access Frozen]]

N/A - cannot be set with this endpoint.

 

[[Patient.Entered Timestamp]]

N/A - cannot be set with this endpoint.

 

[[Patient.Persisted Timestamp]]

N/A - cannot be set with this endpoint.

 

[[Contact]]

For each [[Contact]]:

  • Patient.telecom[x]: ContactPoint

    • system = "email"

    • value = [[Contact.Value]]

[[Contact.Is Primary]] = N/A - cannot be set with this endpoint
[[Contact.Is Confirmed]] = N/A - cannot be set with this endpoint

 

[[National ID]]

  • Patient.identifier[x]: Identifier

    • system = [[national_identifier_system]]

    • value = [[national_identifier_value]]

All national identifier types supported by PKB can be sent into this endpoint. The list of supported types and identifier systems can be found here.

All identifier values provided must be valid for the system in question. Invalid values will result in message rejection.

Multiple identifiers for the same system are invalid, and will lead to message rejection.

At least one national or local identifier is required for patient matching.

[[Local ID]]

  • Patient.identifier[x]: Identifier

    • system = [[local_identifier_system]]

    • value = [[local_identifier_value]]

 Local identifiers may be used as the basis for patient matching, provided they are mapped to PKB-configured organisation or team level identifier types.

The internal PKB unique identifier may also be used for some workflows.

At least one national or local identifier is required for patient matching.

[[Team Alias]]

See interaction description for more details.

Team alias codes are configured on request by PKB.