Demographic RM usage

In the past years I was engaged into discussions about the usability of the openEHR Demographic Package. Sometimes there is a confusion about the purpose of this package, often seen as a simple support for patient’s demographics data (age, gender, names, etc.), but I think it can be much more than that. To describe (verbally) advanced use-cases is not an easy task, better to “put it on paper”.

At Code24 we use the this package since about 2011. These pages are written from both my personal and from Code24 experience and perspective. Hopefully, the followings will give a better overview of the potential of this package.

The package content

This package is part of the openEHR RM, it includes various types descendant or related to PARTY, the most important or relevant here are PERSON, GROUP, ORGANISATION, AGENT, ROLE and PARTY_RELATIONSHIP. Except the last one, all others are persisted using VERSION and VERSIONED_OBJECT and they are all archetyped, as also indicated in the package overview, which means that there can be several templates (and achetypes) giving different meaning to instances of these types. For example, PERSONs can be used to capture Patients as well as ContactPersons or Practitioners just by having different underlying template and potentially different archetype. The specifications are suggesting an example of instances and how should this package be used, but here are no hard requirements or strongly recommended practices.

An important aspect is that on the archetype level Demographic Package is separated from the EHR, thus archetypes are not under the same package (a CLUSTER archetype of EHR cannot be used by Demographics archetypes, and neither inside data instances). On data level, persisted data is done also via CONTRIBUTIONs, but it cannot reside in same ‘space’ as the EHR data. For security reasons, the recommendation is to avoid storing demographic data in patient’s EHR (using of ADMIN_ENTRY compositions), an aspect which is fully supported by the Demographic Package.

Use cases

The openEHR Demographic Package is used by Code24 mainly (but not limited) to:

Handle all Patients and Practitioners and their membership to Care Teams
Support various session data: current user, Role, ACL, definition of caseload, in-app notifications and user preferences.
Register Organisation structure and partnerships, as well as other external care actors (e.g. insurance providers, referrers, GPs).
Support actions taken by internal or external background processes with the use of Agent.
Support for Patient social network, family members, confidants or other delegated Person to have access to Patient’s data.
Support for Admission information, Agendas (Events & calendars), Referrals.

Functionally, the application layer relies on two types of query involving demographics:

pure demographic queries (e.g. retrieving patient’s data, retrieving care teams, patient’s social or care network)
mixed clinical and demographic queries (to retrieve clinical data which references to demographics or which needs to be decorated with demographic data - a sort of joins across clinical with demographics)

Design aspects

Relations

The key for all these use-cases is to set and to use the right PARTY_RELATIONSHIP type of involved actors, as well as always to be consistent about the definition of the source and the target attributes. In general the design follows specifications, all relations being directional, from source towards target PARTY.

These relationship instances are always created persisted when the source PARTY instance changes. If no other data of the source party changed, then any change on these relations them will create a new version of the source PARTY. Both source and target refers to the version container of a party, by using HIER_OBJECT_IDs. The type of the relationship is stored under PARTY_RELATIONSHIP.name attribute. If relations have a time validity component, then the right attributes are used, otherwise it is considered to be always active.

A typical XML representation of a PARTY_RELATIONSHIP looks like:

<relationships archetype_node_id="at0004">
    <name>
      <value>patientOf</value>
    </name>
    <uid xsi:type="HIER_OBJECT_ID">
      <value>dc51c836-7357-3007-9194-7c70861175f3</value>
    </uid>
    <time_validity>
      <lower_unbounded>false</lower_unbounded>
      <upper_unbounded>false</upper_unbounded>
      <lower_included>true</lower_included>
      <upper_included>true</upper_included>
      <lower>
        <value>20181127</value>
      </lower>
      <upper>
        <value>20201130</value>
      </upper>
    </time_validity>
    <source>
      <id xsi:type="HIER_OBJECT_ID">
        <value>520e8da7-0dc9-45eb-bc73-3b38f145f9d6</value>
      </id>
      <namespace>5HB6J4AHXS00KOOW</namespace>
      <type>PERSON</type>
    </source>
    <target>
      <id xsi:type="HIER_OBJECT_ID">
        <value>a08b8c3f-738e-427e-a93e-9c0bbefa7468</value>
      </id>
      <namespace>5HB6J4AHXS00KOOW</namespace>
      <type>GROUP</type>
    </target>
  </relationships>

Target parties can access their reverse relationship by querying data via PARTY.reverse_relationships, but it is always considering the latest version of the source PARTY (i.e. historical reverse relations are not available from target perspective).

Used ACTOR types

The PERSON type is used to represent patients, care providers, administrative personeel, and patient’s family contacts. Distinction is made by the ROLEs associated with PERSONs via PARTY_RELATIONSHIP. This is not the same as the ACTOR.roles, which represents the ROLE taken by a specific ACTOR (PERSON or AGENT) on runtime, from the pool of associated ROLEs for that ACTOR.

Care Teams are implemented as be GROUPs, and they always participate as the target PARTY in a relationship. Patients is part of a Care Team by having a relation with type ‘patientOf', whereas care providers uses 'memberOf’ relationship type.

There is always an assumed owning ORGANISATION (per tenant), without having explicit relations to PERSONs (neither patients, neither care provides), so their relationship implicit. There might be more partner ORGANISATIONs, such as referral providers, 3rd party specialized care providers, insurance companies, or external primary care offices, etc. In some situations, there might be a relation between PERSONs and such ORGANISATIONs, where the PERSON is always the source.

In some situations, there are GROUPs having relations to other GROUPs or to ORGANISATIONs, persisting such PARTY_RELATIONSHIP is similar to the use cases for PERSONs.

The AGENT type is also used to associate actions being taken by background daemons and jobs. They have no relationship defined.

The ROLE.capabitility.name attribute of a ROLE of PARTY that acts as a target in a relationship, controles the relation type between a source and the target PARTY. In other words, Patient X will have a relation GP with a Care Provider Y, only if Y has a ROLE with GP capability.

Patient Index

From security reasons there is no direct link between patient PARTY instance and the EHR. This logical relation is stored separately in an encrypted way and managed by a separate index service. All cross-referring DV_URIs, LINKs, OBJECT_REFs or PARTY_REFs share same principle and have their identifiers encrypted. This undoubtedly puts a high pressure on any query mechanism that needs to mix clinical with demographic data, requiring various pre- and post-processing techniques in and around the query engine.

Models

Very schematically, the PERSONs are modelled like:

PERSON:
  name: "person"
  uid: <OBJECT_VERSION_ID>
  identities[openEHR-DEMOGRAPHIC-PARTY_IDENTITY.person_name.v2]: <PARTY_IDENTITY>
  contacts: 
    - addresses[openEHR-DEMOGRAPHIC-ADDRESS.address.v2]
    - addresses[openEHR-DEMOGRAPHIC-ADDRESS.electronic_communication.v2]
  relationships:
    - <PARTY_RELATIONSHIP>  
  details[openEHR-DEMOGRAPHIC-ITEM_TREE.person_details.v2]:
    - items[at0001, birthday]  
    - items[at0031, gender]
  role: 
    - <PARTY_REF>

A GROUP (and the ORGANISATION) is more simpler, because they don’t have relations and neither roles:

GROUP:
  name: "group"
  uid: <OBJECT_VERSION_ID>
  identities[openEHR-DEMOGRAPHIC-PARTY_IDENTITY.group_name.v2]: <PARTY_IDENTITY>
  contacts: 
    - addresses[openEHR-DEMOGRAPHIC-ADDRESS.address.v2]
    - addresses[openEHR-DEMOGRAPHIC-ADDRESS.electronic_communication.v2]
  details[openEHR-DEMOGRAPHIC-ITEM_TREE.group_details.v2]:
    - items

Specifications Issues

Although the package is already usable in production settings, there are a few issues in specifications that still needs to be solved in order to expect a broader adoption:

introduce the SYSTEM type
define SYSTEM as the owner of demographic CONTRIBUTIONs
AQL support for Demographic RM
URI scheme definition, support for LINKs
REST Api support