Developer documentation‎ > ‎FHIR® REST API‎ > ‎Roadmap‎ > ‎Operations‎ > ‎

Process Message


https://www.hl7.org/fhir/STU3/operation-messageheader-process-message.html

Status

In development. API spec subject to change.

Overview

PKB implements the $process-message operation as defined by the FHIR specification, in order to allow a client to submit a message for processing.

PKB only support asynchronous message processing, so a URL parameter of "async=true" must be provided.

PKB will outline a Message Definition for each event that we support. Some behaviour will be common to all messages as part of the general $process-message specification. Each message will have its own business logic rules defined in the corresponding message definition.

The first message PKB will support is the ability to create or update a patient's demographics, including triggering an email invitation.

Endpoints

Interaction HTTP URL Supported Parameters Permitted User Types Description Examples
operation POST /$process-message
  • async=true. Required. 
  • System User
 Submit message to PKB for processing. /$process-message?async=true

Message Definition: Create or Update Patient

Purpose of message
  • Create or update the demographics of a single patient
  • Optionally trigger an email invitation to that patient

Server behaviour

Synchronous transport-level acceptance
  1. Message validation.
    1. If the message is superficially valid: an HTTP 200 OK (no body) will be returned immediately. This acknowledges successful receipt, but does not indicate the message has necessarily been processed.
    2. Else: an appropriate HTTP error code will be returned, along with a FHIR OperationOutcome where possible.
Asynchronous processing
  1. Validate. Validate mandatory data
    1. Duplicate message check.
      1. Return an error if any of the following conditions are true:
        1. Bundle.identifier contains a value that PKB has previously received from this sender (where sender is scoped to the API client, regardless of the source organisation)
        2. MessageHeader.id contains a value that PKB has previously received from this sender (where sender is scoped to the API client, regardless of the source organisation)
    2. ODS check.
      1. Return an error if any of the following conditions are not true:
        1. an ODS code has been provided in Patient.meta.tag
        2. this matches the ODS code of an existing PKB organisation
        3. that organisation has granted the sending client authorisation to interact with the FHIR API on their behalf
    3. Patient identifier check.
      1. Return an error if any of the following conditions are not true:
        1. An NHS number has been provided
        2. The status of the NHS number has been provided
        3. The status is 01
    4. Return an error if a given name is not present
    5. Return an error if a family name is not present
  2. Create or update. Search for the patient, based on their identifier. This will search across the entire server, and will not be limited to records that the caller has access to.
    1. If no matches:
      1. Create a new medical record in the default team of the PKB organisation for the matching ODS code.
    2. If one match:
      1. Update the demographic details with those provided in the message.
    3. If multiple matches:
      1. Return an error. Note: this should never happen if searching by NHS number.
  3. Invite. Invite the patient to register via email if the following conditions are true. If they are not true, silently skip the invitation step.
    1. The patient was not already registered (either they did not exist, or they existed but weren't registered, regardless of whether they had been sent an invitation via any route)
    2. A date of birth is recorded for the patient
    3. An email address was provided
    4. The key to the medical record is already available to the org
  4. Consent.
    1. If there is no consent record between the patient and the default team of the PKB organisation for the matching ODS code:
      1. If the key to the medical record is already available to the org: create a new consent record. The discharged marker will be false, and the team should be granted their default privacy labels.
      2. Else: no action
    2. Else
      1. If the discharged marker on the existing consent record is true: set it to false
      2. Else: no action
  5. Respond. A response, as defined below, is sent to the caller's $process-message endpoint.

Request

FHIR PKB Notes
Bundle.identifier
  • identifier: Identifier
    • value. A sender-assigned UUID.
Bundle.type "message"
Bundle.entry[0]: BackboneElement
  • resource: MessageHeader
MessageHeader.id
  • id. A sender-assigned UUID for the message.
  
MessageHeader.event
  • event
    • system = "http://fhir.patientsknowbest.com/codesystem/message-event"
    • code = "create-or-update-patient"
MessageHeader.destination
  • destination
    • endpoint. The absolute URL of the PKB $process-message endpoint.
MessageHeader.timestamp
  • timestamp
MessageHeader.source
  • source
    • endpoint. This must be set to a pre-agreed value configured for the sender's API Client ID. This is the location to which PKB will send the asynchronous response.
Bundle.entry[1]: BackboneElement
  • resource: Patient
Patient.meta
  • meta
    • tag
      • system = "https://fhir.nhs.uk/Id/ODS-Code"
      • code. The ODS code of the source organisation for this demographic update.
  
Patient.identifier
  • identifier: Identifier
    • extension
      • url = "https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1"
      • valueCodeableConcept
        • coding
          • system = "https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1"
          • code = "01"
    • value. The NHS number of the patient.
    • system = "https://fhir.nhs.uk/Id/nhs-number"
Patient.name
  •  name: HumanName
    • family = [[User.Family Name]]
    • given[0] = [[User.Given Name]]
    • prefix[0] = [[User.Title]]
  
Patient.telecom
  • telecom: ContactPoint
    • system = "email"
    • value = [[Contact.Value]]
Patient.telecom
  • telecom: ContactPoint
    • system = "phone"
    • value = [[Patient.Phone]]
Patient.gender
[[Patient.Gender]]

[[Patient.Gender]] code mappings (FHIR → PKB):
  • unknown → UNKNOWN
  • male → MALE
  • female → FEMALE
  • other → INDETERMINATE
Patient.birthDate [[Patient.Date of Birth]]  
Patient.deceased[x]<conditional>
If the patient is recorded as dead and the death timestamp is known:
  • deceasedDateTime = [[Patient.Death Timestamp]]
Else if the patient is recorded as dead but a death timestamp has not been recorded:
  • deceasedBoolean = true
Else
  • deceasedBoolean = false
 
Patient.address
  • address: Address
    • line[0] = [[Patient.Address Line 1]]
    • line[1] = [[Patient.Address Line 2]]
    • city = [[Patient.City]]
    • state = [[Patient.State]]
    • postalCode = [[Patient.Postal Code]]
    • country = [[Patient.Country]]

Example Request

{
  "resourceType": "Bundle",
  "identifier": {
    "value": "501fbbea-cfce-4b80-98fb-6cda85fcd9fb"
  },
  "type": "message",
  "entry": [
    {
      "resource": {
        "resourceType": "MessageHeader",
        "id": "8442bcb0-49e2-494b-bea9-40da630d4a27",
        "event": {
            "system": "http://fhir.patientsknowbest.com/codesystem/message-event",
            "code": "create-or-update-patient"
        },
        "destination": [
          {
            "endpoint": "https://sandbox.patientsknowbest.com/fhir/$process-message"
          }
        ],
        "timestamp" : "2020-04-01T11:12:13+00:00",
        "source": {
          "endpoint": "https://sender.com/fhir/$process-message"
        }
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "tag": [
            {
              "system": "https://fhir.nhs.uk/Id/ODS-Code",
              "code": "P123456"
            }
          ]
        },
        "identifier": [
          {
            "extension": [
              {
                "url": "https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1",
                "valueCodeableConcept": {
                  "coding": [
                    {
                      "system": "https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1",
                      "code": "01"
                    }
                  ]
                }  
              }
            ],
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9999999999"
          }
        ],
        "name": [
          {
            "family": "Smith",
            "given": [
              "John"
            ],
            "prefix": [
              "Mr"
            ]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "07123456789"
          },
          {
            "system": "email",
            "value": "john.smith@example.com"
          }
        ],
        "gender": "male",
        "birthDate": "1990-01-02",
        "address": [
          {
            "line": [
              "1 Main Street",
              "The Place"
            ],
            "city": "London",
            "postalCode": "CB11BC"
          }
        ]
      }
    }
  ]
}


Response

FHIR PKB Notes
Resource id
 
Bundle.identifier
  • identifier: Identifier
    • value. A PKB-specified UUID.
Bundle.type "message"
Bundle.entry[0]: BackboneElement
  • resource: MessageHeader
MessageHeader.id
  •  id. A PKB-assigned UUID for the message.
  
MessageHeader.event
  • event
    • system = "http://fhir.patientsknowbest.com/codesystem/message-event"
    • code = "create-or-update-patient"
MessageHeader.destination
  • destination
    • endpoint. MessageHeader.source.endpoint of the request.
MessageHeader.timestamp
  • timestamp
MessageHeader.source
  • source
    • name = "Patients Know Best"
    • endpoint. The absolute URL of the PKB $process-message endpoint.
MessageHeader.response
  • response
    • identifier. MessageHeader.id of the request.
    • code. ok | transient-error | fatal-error
    • details. Optional reference to a contained OperationOutcome resource.

Example Response

{
  "resourceType": "Bundle",
  "identifier": {
    "value": "932006ea-3206-4735-9f27-a1449af0c34e"
  },
  "type": "message",
  "entry": [
    {
      "resource": {
        "resourceType": "MessageHeader",
        "id": "8e46a6b5-2ff2-48c8-b40f-e304e7af028b",
        "event": {
          "system": "http://fhir.patientsknowbest.com/codesystem/message-event",
          "code": "create-or-update-patient"
        },
        "destination": [
          {
            "endpoint": "https://sender.com/fhir/$process-message"
          }
        ],
        "timestamp" : "2020-04-01T11:12:14+00:00",
        "source": {
          "name": "Patients Know Best",
          "endpoint": "https://sandbox.patientsknowbest.com/fhir/$process-message"
        },
        "response": {
          "identifier": "8442bcb0-49e2-494b-bea9-40da630d4a27",
          "code": "ok"
        }
      }
    }
  ]
}

Comments