Team membership

Overview

Patients are linked to the Teams which care for them by way of a Consent Record.

They control the level of access each Team has by making use of their Sharing settings.

This page outlines the technical details of how to use the HL7 API to ensure your patients are automatically added to the correct Teams for your deployment.

Linked Teams

Determining the Linked Teams (the set of Teams caring for the patient) for an HL7 message sent to a particular patient is a 3 step process.

1: Source Organisation / Team

When connecting to PKB, the Source Organisation and/or Source Team are initially determined from the authentication credentials provided.

It is additionally possible to modify the Source Team through use of an alias in MSH-4.

2: Creating Team

When creating a record, exactly one Team will be identified as the Creating Team. The Creating Team will be determined as follows:

  • If the connection is authenticated as an HL7 Partner:

    • The Creating Team will be the default team (if present) for the corresponding grant issued by the Source Organisation on whose behalf the Partner is currently connecting

  • Else if a Source Team is present on the authenticated connection (for example, if the Source Organisation is using an MSH-4 alias to identify a specific Source Team for the current message):

    • That Source Team will also be treated as the Creating Team

  • Else:

    • The Creating Team will be the default team (if present) for the Source Organisation

Note: It is an error to try to create a new medical record if a Creating Team could not be determined.

3: Linked Teams

The newly created record will be added to one or more Teams in PKB, determined as follows:

  • If the message was a demographic update, and a ZTM segment was provided:

    • The Team list will be determined from the contents of the ZTM segment

  • Else:

    • The medical record will be linked to the Creating Team only

Creating vs updating

Creating

An HL7 message for an unknown patient will create a new medical record if either:

  • The message was a demographic update (either an ADT A28 or ADT A31)

  • The auto-create configuration option has been enabled for the interface

A new medical record will not have any existing links to any Teams, and so a new Consent Record will be created for each Linked Team.

Updating

When an HL7 message is processed for medical record that already exists, PKB will make sure a Consent Record exists for each Linked Team, regardless of whether the message was a demographic update or whether auto-create was enabled.

Consent management

When creating a new Consent Record via this workflow, the default privacy labels for the Team will automatically be granted.

If the Linked Teams workflow finds a Consent Record is already in place, it will not modify it. For example, if the patient had previously chosen to change the privacy labels granted to the Team, this workflow will not overwrite those preferences.

Admission management

When creating a new Consent Record, the patient will be considered to be admitted to the corresponding Team.

If the Linked Teams workflow finds a Consent Record is already in place, it will not modify it. For example, if the patient had previously been discharged from a Team, sending them additional data will not automatically re-admit them.

Notably, this is true even if the HL7 message is relates to a real-world admission or discharge (e.g. an ADT A01 or ADT A03).