openEHR logo

openEHR Platform Service Model

Issuer: openEHR Specification Program

Release: SM latest

Status: TRIAL

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: openehr, service, API

openEHR components
© 2017 - 2020 The openEHR Foundation

The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations.

Licence

image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/

Support

Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser Completed

SM Release 1.0.0

0.9.7

Add Subject Proxy Service and Data set package.

T Beale

14 Oct 2020

0.9.6

Adjust naming and definitions of elements in RESULT_SET classes to reflect REST API.

S Iancu

25 Mar 2020

0.9.5

Add missing enumeration invalid_artefact to DEFINITION_CALL_STATUS_TYPE (SPECPR-293);
Add xxx_count() calls to I_DEFINITION_XX interfaces (SPECPR-288);
Rename row_offset and rows_to_fetch to item_offset and items_to_fetch (SPECPR-292);
Change names of list_all_xxx() functions in definitions interfaces to list_xxx() (SPECPR-292);
Added valid_xxx() calls and preconditions to upload_xx() calls in I_DEFINITION_XX interfaces (SPECPR-291);
Remove duplicate operation I_EHR.list_contributions() (SPECPR-304);
Improve documentation of implicit server-side Contribution and Version creation (SPECPR-305);
Correct argument types of I_EHR_COMPOSITION.get_composition_xx() functions; rename get_composition() to get_composition_latest().

P Pazos

28 Feb 2019

Add I_DEFINITIONS_CHECKER and DEFINITIONS_CHECKER_STATUS to support definitions validity pre-conditions.

T Beale

16 Jan 2019

0.9.4

Improve documentation text;
Reverse order of Parameter and Errors sections in operations text.

T Beale

22 Aug 2018

0.9.3

Improve documentation text;
Add section on call conventions; improve query register calls based on REST API 0.9.0.
Add EHR Index section.

T Beale

14 Feb 2018

0.9.2

Improve documentation text;
remove auth_tok argument from calls.

T Beale

22 Oct 2017

0.9.1

Added demographic interface calls;
added more admin interface calls.

T Beale

18 Oct 2017

0.9.0

SPECSM-1: Initial writing.

openEHR SEC

15 Sep 2017

Acknowledgements

Primary Author

  • Thomas Beale, Ars Semantica; openEHR Foundation Management Board.

Contributors

This specification has benefited from formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.

  • Pablo Pazos, Principal, Cabloabs, Uruguay

Trademarks

  • 'openEHR' is a registered trademark of the openEHR Foundation

1. Preface

1.1. Purpose

This document specifies core components of the openEHR platform in a formal, abstract form, for use in developing concrete service API definitions such as SOAP, REST, Google protocol buffers and other interface technologies.

The intended audience includes:

  • Standards bodies producing health informatics standards;

  • Solution vendors.

Prerequisite documents for reading this document include:

Related documents include:

1.3. Status

This specification is in the TRIAL state. The development version of this document can be found at https://specifications.openehr.org/releases/SM/latest/openehr_platform.html.

Known omissions or questions are indicated in the text with a 'to be determined' paragraph, as follows:

TBD: (example To Be Determined paragraph)

1.4. Feedback

Feedback may be provided on the technical mailing list.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the SM component Change Request tracker.

1.5. Conformance

Conformance of a data or software artifact to an openEHR specification is determined by a formal test of that artifact against the relevant openEHR Implementation Technology Specification(s) (ITSs), such as a REST API interface or an XML-schema. Since ITSs are formal derivations from underlying models, ITS conformance indicates model conformance.

2. Overview

2.1. General Assumptions

In order to specify concrete service interfaces (i.e. APIs) to openEHR platform product components, a formal, abstract definition of the platform interfaces is useful, so as to be able to state the formal interface call semantics independent of any particular implementation technology. This approach clarifies the distinction between required semantics and the details contingent in any concrete technology, such as SOAP/WSDL, REST, and so on, each of which has its own characteristics and rules.

It is assumed that native APIs are network-accessible via one or more communications protocols, each with an appropriate protocol adapter. Such protocols include the text-based, such as SOAP/WSDL and REST, as well as the many binary protocols, including Google Protocol Buffers, Apache Thrift, Kafka, ZeroC ICE, and Advanced Message Queueing Protocol (AMPQ). The focus of this specification is the nominal 'native API' that is reached by any of these methods, as shown below.

assumed model
Figure 1. Assumed Architecture

2.2. openEHR Platform Model

The following figure illustrates the components of the abstract openEHR Platform, along with their interfaces.

SM platform.definition
Figure 2. sm.platform.definition Package

Each component has one or more associated interfaces, i.e. abstract service definitions which define a transactional interface to the service represented by the component. Each interface consists of a number of calls, and each call is defined in an abstract way, i.e. independent of the representations and expressions required by a concrete protocol.

This view does not attempt to define a real product architecture as would be developed by an openEHR platform implementor, but it does establish a formal equivalent of any such architecture. Practically, this entails standardised naming of components and the semantics of their logical interfaces so that platform procurers and users can unambiguously refer to the 'Admin service' or the 'EHR service' within technical or commercial documents. The abstract service architecture described here provides platform implementers a standard reference definition for mapping agreed functionality (such as requested in a tender or other solicitation) into their own architectures, which may be organised quite differently.

The services are as follows.

Service Description

Definitions

Service enabling upload and querying of definition artefacts, including archetypes, templates and queries.

EHR

Versioned persistence service for EHRs.

Demographic

Versioned persistence service for demographic data.

EHR Index

EHR id / demographic subject cross-reference service.

Query

Service providing AQL query retrieval for EHR, demographics and other content services.

Terminology

Service providing access to terminology, including intentional value sets.

Message

Message import and export service, supporting multiple message formats as we as EHR Extracts and documents.

System Log

IHE ATNA-compliant system log.

Subject Proxy

Service for registering subject-focussed data-sets that provide a 'proxy' picture of the subject over time.

Admin

Service providing administrative facilities on all services in the installed environment, such as back-up.

2.3. Interface Calls

Regardless of the internal organisation of real product architectures, agreement across a community of producers and users of products that claim to conform to a published platform specification, must by definition be based on something formally statable and testable. As noted above, this is described here in the form of logical components which have logical interfaces, each consisting of a set of calls, of which the latter constitute the finest level of specification.

A logical interface call is understood here in the standard computer science manner, i.e. as a callable routine with a formal, typed signature. Good practice usually dictates that such routines should take the form of either pure functions, or pure procedures, but not both: side-effect producing functions should generally be avoided. In other words, interface calls are either queries that return something but do not change state, or commands that cause a change, but don’t compute or return anything. The separation is sometimes known as command / query separation.

The signatures of query and procedure calls thus take the following syntactic forms:

    func: T                                 -- function with no arguments
    func(arg1: X, arg2: Y, arg3: Z): T      -- function with arguments

    proc                                    -- procedure with no arguments
    proc(arg1: X, arg2: Y)                  -- procedure with arguments

One of the key assumptions of this specification (and indeed formal standardisation in general) is that although real implementations of a platform may have differently structured components and different naming of functions, arguments etc, that there is a formal equivalence between calls specified in a published standard and those in the implementation. Thus, it must be the case that even if three calls in an implementation are required to achieve the effect of a single call in this specification, that the conditions described here prior and after the call(s) are the same in both cases, and also that the three calls taken together are transactionally protected. If this is not true, it implies that the implementation is introducing unspecified semantics.

2.4. Anatomy of an Abstract Call Specification

A fuller specification of any function or procedure includes its semantics, stated in terms of pre-conditions, post-conditions and exceptions, along with documentation of the same. This is exactly as found in any standard library in most programming languages, and indeed, standardised meta-data keywords and labelling have evolved in most programming documentation systems to support exactly this kind of specification, even where the language doesn’t directly support some of its features, such as pre- or post-conditions.

This specification uses the same form of specification, which can be illustrated as follows:

Call

create_ehr_with_id

This call creates a new EHR in the EHR persistence service, with …​.

Arguments

an_id: UUID

A UUID that will be used as the EHR’s ehr_id.

Pre-conditions

Valid_id: not has_ehr (an_id)

No EHR with ehr_id = an_id currently exists.

Post-conditions

Ehr_created: has_ehr (an_id)

An EHR with ehr_id = an_id has been created.

Exceptions

Ehr_already_exists

EHR with an_id already exists.

Auth_error

Caller authorisation failure.

The above kind of specification can in general be easily mapped to any concrete API technology. In each case, how the arguments are expressed, details of serialisation (for text-based technologies like SOAP and REST), error handling, etc, will be different. Google protocol buffers for example uses an OMG IDL-like approach to specification, i.e. structured type definitions. REST on the other hand is a web-based type of API normally mapped onto HTTP verbs, URIs and HTTP error codes.

The intent of the current specification is thus to express the abstract element of each interface call, so that both back-end semantics can be correctly designed, and API definitions can be correctly written and tested.

2.5. Global Conventions

2.5.1. Functional Style

Various ways of expressing service interface functions to underlying resources are possible, with choices available in various dimensions:

  • stateless / mostly stateless / stateless;

  • approach to access control and authorisation;

  • single interface / composed interface ;

  • full argument lists / parameter-carrying object arguments / mixture.

In real implementations, different choices will be made; all that matters is that the implementation contains one or more calls that can be made for each call documented here, with the same transactional semantics. Consequently, the functional style used in this specification does not need to be exactly replicated in either a back-end or an API, only the resulting semantics do.

Here we use a nearly stateless approach, where the exception is to use a second call to determine success status and any error information. This can easily be mapped to a fully stateless style, as would be used in a server driven by a managed request queue. This approach enables functions to be declared in a standard programming style, with return types reflecting successful execution. The function declarations are accordingly of the following style:

// definition

interface I_EHR_SERVICE : I_STATUS {
    Boolean has_ehr(UUID an_ehr_id);
    UUID create_ehr();
    UUID create_ehr_with_id(UUID an_ehr_id);
}

Authentication and authorisation is assumed to have been dealt with before any particular call has been made by a combination of standard authentication technologies (e.g. OAuth, RFC 7235) and role-based access control.

Failures are dealt with by calling a standard function last_call_failed() and if True, calling last_call_status() which returns a structured error object. This enables the recording of errors (such as authorisation failure), pre-condition exceptions (generally relating to argument vaidity) and server exceptions (equivalent to post-condition or invariant exceptions). This leads to the following typical call sequence for calls defined in this specification.

I_EHR_SERVICE i_ehr_service;
CALL_STATUS call_status;
UUID test_result, result, an_ehr_id;

try {
    test_result = i_ehr_service.create_ehr_with_id(an_ehr_id);
    if (i_ehr_service.last_call_error())
        call_status = i_ehr_service.last_call_status();
    else
        result = test_result;
}
catch (PreConditionException e) {
    // deal with pre-condition violations

    call_status = new CallStatus(CallStatuses.precondition_violation)
    // set any other information
}
catch (Exception e) {
    // deal with other exceptions

    call_status = new CallStatus(CallStatuses.exception)
    // set any other information
}


// package up call_status, result in response

Apart from error-handling, the interfaces are stateless in the sense that any single call constitutes a self-standing transaction on the back-end service, i.e. a transaction that when executed on the service will leave it in a consistent state.

The above illustrates just one pattern of calling in a server. Another common style is to include results as 'out' parameters, and to use the return value to return call status. Either style can be used, and can be trivially mapped from one to the other. No such code is intended to implemented directly; the above is merely a way of explaining the semantics within context of the interface calls documented in this specification.

2.5.2. List Handling

Calls that produce a container result potentially containing unlimited numbers of elements can be managed in a typical 'DB cursor' fashion, i.e. by setting the following parameters:

item_offset

Optional parameter specifying offset in query result items to at which to start returning items, starting at zero. An offset of 1 means that the first item to return is the 2nd item. Zero signifies that items starting from the first item should be returned.

items_to_fetch

Optional parameter specifying number of result items to fetch, starting from the item indicated by item_offset. A zero means 'all'.

2.5.3. Global Naming Conventions

The following naming conventions are used for naming parameters throughout this specification, where they apply.

Term Description

ehr_id

The value for an EHR identifier, stored under EHR.ehr_id.value, usually an UUID or GUID

versioned_object_uid

The value of a VERSIONED_OBJECT unique identifier, i.e. VERSIONED_OBJECT.uid.value,
e.g. 8849182c-82ad-4088-a07f-48ead4180515

version_uid

The value of a VERSION unique identifier, i.e. VERSION.uid.value,
e.g. 8849182c-82ad-4088-a07f-48ead4180515::example.domain.com::2

preceding_version_uid

The value of a previous VERSION unique identifier,
e.g. 8849182c-82ad-4088-a07f-48ead4180515::example.domain.com::1

object_id

A placeholder for either versioned_object_uid or version_uid identifier

time

A date-time in ISO 8601 format (e.g. 2015-01-20T19:30:22.765+01:00)

2.6. Package Structure

The openEHR Platform Service Model package structure is illustrated below. It consists of the packages common, definition and interface. The second contains the service components, while the third contains the interfaces attached to each service component.

SM platform packages
Figure 3. sm.openehr_platform Package Overview

3. Common Package

3.1. Overview

The platform.common package shown below defines common elements of the platform service model, including:

  • I_STATUS / CALL_STATUS: a representation of the status result of any call execution;

  • UPDATE_VERSION: an information structure suitable for committing data to a versioned store based on the openEHR versioning (change control) specification;

  • PLATFORM_SERVICE: an enumeration of the available services, used in various interfaces.

SM platform.interface.common
Figure 4. sm.openehr_platform.platform_common package

3.2. Representing Call Status

The status of a call is represented using a CALL_STATUS object containing various informational fields and a code attribute that carries a value from the enumerated type CALL_STATUS_TYPE or a descendant. The codes defined in CALL_STATUS_TYPE are generic and apply across all services. Particular services may add more codes by inheriting from this class and defining further specific codes.

3.3. Version Update Semantics

Some of the interfaces defined in this specification cause creation or update of a versioned 'top-level' openEHR object, i.e. a COMPOSITION, PARTY or similar. Such calls implicitly require the creation of a new CONTRIBUTION on the server side, as well as one or more new ORIGINAL_VERSION objects, and in creation cases, new VERSIONED_OBJECTS.

To perform this work on the server, the UPDATE_VERSION<T> structure is provided in order to enable the appropriate meta-data to be supplied by the caller, leaving out parts that are generated by the service. Thus, a partial version of AUDIT_DETAILS called UPDATE_AUDIT is used, since the time_committed and system_id attributes need to be generated on the server. ATTESTATION instances can be supplied in their full form.

The preceding_version_uid attribute must be specified, except in the case where the version update is a first version. The lifecycle_state must be supplied in all cases, which is a value such as 532|complete|, 553|incomplete|, 523|deleted|, etc from the openEHR terminology.

This approach allows the server side to create the required new ORIGINAL_VERSION<T> object, rather than the client trying to do it.

For each storable top-level type such as COMPOSITION, FOLDER, PARTY descendants etc, a new concrete type may be derived from UPDATE_VERSION<T>. For example, for COMPOSITION, the type UV_COMPOSITION may be defined, inheriting from UPDATE_VERSION<COMPOSITION>.

3.4. Class Definitions

3.4.1. I_STATUS Interface

Interface

I_STATUS

Description

Interface to obtain status of previous calls; use by inheritance.

Functions

Signature

Meaning

1..1

last_call_failed (): Boolean

Return True if the last call generated an error, i.e. any result other than CALL_STATUSES.success.

1..1

last_call_status (): CALL_STATUS

Class status object for last call.

3.4.2. CALL_STATUS Class

Class

CALL_STATUS

Description

Object representing a call status.

Attributes

Signature

Meaning

1..1

code: CALL_STATUS_TYPE

Call status code for last call.

1..1

call_name: String

Name of call that this status documents.

1..1

call_string: String

Full call, in stringified form, including arguments. Non-primitive objects are shown as addresses unless an exported as_string() method is available.

1..1

meaning: String

Meaning of the result status.

1..1

message: String

Error message text.

3.4.3. CALL_STATUS_TYPE Enumeration

Enumeration

CALL_STATUS_TYPE

Description

Enumeration representing standard call statuses.

Attributes

Signature

Meaning

success

Call succeeded.

auth_failure

Authorisation failure.

precondition_violation

Precondition violation occurred.

object_version_does_not_exist

Referenced Object version of a Versioned Object does not exist.

versioned_object_does_not_exist

No Versioned Object with referenced identifier found.

exception

Exception other than precondition violation occurred.

ehr_id_does_not_exist

Ehr provided id not found.

party_id_does_not_exist

Party with provided id not found.

file_not_writable

File system locator cannot be written to.

version_mismatch

3.4.4. UPDATE_VERSION Class

Class

UPDATE_VERSION<T> (abstract)

Description

An object representing an update to an existing VERSION within a VERSIONED_OBJECT, that can be provided by a client to the platform. The back-end will construct a full VERSION<T> object from this and server-side generated data items. If this represents the first version, it will also construct a new VERSIONED_OBJECT first.

Attributes

Signature

Meaning

0..1

preceding_version_uid: OBJECT_VERSION_ID

Current version in service for which this version is an update (i.e. the version that is preceding relative to this version update).

1..1

lifecycle_state: Terminology_code

Lifecycle state of the content item in this version.

0..1

attestations: List<ATTESTATION>

Set of attestations relating to this version.

1..1

data: T

Data item being provided in this Version update. Must conform in type to the expected type, which is normally constrained using a derivative class like VU_XX that binds T to a particular type such as COMPOSITION etc.

1..1

audit: UPDATE_AUDIT

Audit details for this update.

3.4.5. UPDATE_AUDIT Class

Class

UPDATE_AUDIT

Description

The set of attributes required to document the committal of an information item to a repository. Used by the server to create an AUDIT_DETAILS object.

Attributes

Signature

Meaning

1..1

change_type: Terminology_code

Type of change. Coded using the openEHR Terminology audit change type group.

0..1

description: String

Reason for committal.

1..1

committer: PARTY_PROXY

Identity and optional reference into identity management service, of user who committed the item.

Invariants

Change_type_valid: terminology (Terminology_id_openehr).has_code_for_group_id (Group_id_audit_change_type, change_type.defining_code)

3.4.6. I_VALIDITY_CHECKER Interface

Interface

I_VALIDITY_CHECKER

Description

Utility functions for checking validity of use of definitions within data.

Functions

Signature

Meaning

1..1

definitions_valid (
a_content: LOCATABLE[1]
): Boolean

Return True if the definition identifiers (i.e. archetype and template identifiers) are known in the local definitions service.

1..1

content_valid (
a_content: LOCATABLE[1]
): Boolean

Return True if the content structure is a valid instance of the relevant RM classes.

3.4.7. VALIDITY_CHECKER_STATUS Enumeration

Enumeration

VALIDITY_CHECKER_STATUS

Description

Enumeration representing I_DEFINITIONS_CHECKER statuses.

Attributes

Signature

Meaning

definition_unknown

The content object contains definition identifiers not known in the local definitions service.

content_invalid

The content object is not a valid instance of its reference model classes.

4. Definition Package

4.1. Overview

The platform.interface.definitions package shown below defines service interface to the definitions component in the logical platform architecture.

SM platform.interface.definitions
Figure 5. sm.platform.interface.definitions package

The interfaces provided in this service are designed to enable any model-like or reference artefacts, other than terminology, to be stored for use by the rest of the system. This includes archetypes, templates, queries, and query sets.

4.2. Archetypes and Templates

The I_DEFINITION_ADL14 and I_DEFINITION_ADL2 interfaces are provided to enable upload, updating and removal of archetypes and templates based on the ADL 1.4 and ADL 2 standards respectively, for use in an operational system.

In the ADL2 case, archetypes and 'templates' are all instances of archetypes, formally speaking, which means that both source artefacts and Operational Templates (OPTs) can be uploaded. All such artefacts are identified in the same way, via an Archetype human-readable identifier (ARCHETYPE_HRID) and a UUID.

For ADL 1.4, 'templates' are distinct artefacts, and the service enables the upload of source archetypes and ADL 1.4 - based OPTs, which are XML artefacts. In ADL 1.4, archetypes are identified with the older ARCHETYPE_ID, while OPTs are identified with UUIDs.

4.3. Registered Queries

Queries may be registered in the system for later execution. They are identified by 'qualified names', i.e. String names that may include a namespace and optionally a formalism type. The following schemes may be used:

  • <namespace>::<query-name>

  • <namespace>::<formalism>::<query-name>

Examples:

  • "ehr::all_influenza_vacc_candidates"  — a query for candidates for influenza vaccination

  • "demographic::inpatients_rns"  — a demographic query for current in-patients of RNS hospital

  • "task_planning::aql::chemotherapy_plans"  — an AQL query for chemotherapy plans

If no namespace is supplied, the namespace "misc" is assumed.

4.4. Class Definitions

4.4.1. I_DEFINITION_ADL2 Interface

Interface

I_DEFINITION_ADL2

Description

Interface to ADL2 definitions (i.e. models) in an EHR 'system'.

Functions

Signature

Meaning

1..1

has_artefact (
an_id: ARCHETYPE_HRID[1]
): Boolean

Return True if AOM2 artefact with id an_id exists in the service.

1..1

valid_artefact (
an_artefact: AUTHORED_ARCHETYPE[1]
): Boolean

Test validity of artefact.

0..1

upload_artefact (
an_artefact: AUTHORED_ARCHETYPE[1]
)

Pre_valid: valid_artefact (an_arch)
Post_has_artefact: has_artefact (an_arch.identifier)

Upload an ADL2 artefact, i.e. archetype, template or operational_template. If an artefact with the same physical identifier and namespace exists, replace it.

The artefact must validate.

Errors
  • invalid artefact (+ specific messages)

1..1

get_artefact (
an_id: ARCHETYPE_HRID[1]
): AUTHORED_ARCHETYPE

Pre_artefact_exists: has_artefact (an_id)

Get the AOM2 artefact with id an_id.

Errors
  • artefact_does_not_exist

0..1

list_artefacts (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

List all AOM2 artefacts known in the service.

0..1

list_archetypes (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

List all archetypes, i.e. artefacts whose concrete type is AUTHORED_ARCHETYPE.

0..1

list_templates (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

List all archetypes, i.e. artefacts whose concrete type is TEMPLATE.

0..1

list_opts (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

List all archetypes, i.e. artefacts whose concrete type is OPERATIONAL_TEMPLATE.

0..1

list_matching_artefacts (
id_pattern: String[1],
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

List all artefacts whose identifiers match a regex pattern.

Errors
  • invalid_id_pattern

0..1

delete_artefact (
an_id: ARCHETYPE_HRID[1]
)

Delete the AOM2 artefact with id an_id.

Errors
  • artefact_does_not_exist

1..1

artefacts_count (): Integer

Return total artefacts count.

1..1

archetypes_count (): Integer

Return total archetypes count.

1..1

templates_count (): Integer

Return total templates count.

1..1

opts_count (): Integer

Return total OPTs count.

4.4.2. I_DEFINITION_ADL14 Interface

Interface

I_DEFINITION_ADL14

Description

Interface to ADL 1.4 definitions (i.e. archetypes and OPTs) in an EHR 'system'.

Functions

Signature

Meaning

1..1

has_archetype (
an_id: ARCHETYPE_ID[1]
): Boolean

Return True if an ADL 1.4 archetype with id an_id exists in the service.

1..1

valid_archetype (
an_arch: ARCHETYPE[1]
): Boolean

Test validity of archetype an_arch.

0..1

upload_archetype (
an_arch: ARCHETYPE[1]
)

Post_has_archetype: has_archetype (an_arch.identifier)

Upload a valid ADL 1.4 archetype. If an archetype with the same id already exists, replace it. The archetype must be valid to succeed.

Errors
  • invalid_archetype

1..1

get_archetype (
an_id: ARCHETYPE_ID[1]
): ARCHETYPE

Get the ADL 1.4 archetype with id an_id.

Errors
  • artefact_does_not_exist

0..1

list_archetypes (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_ID>

List all ADL 1.4 archetypes known in the service.

0..1

list_matching_archetypes (
id_pattern: String[1],
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_ID>

List all archetypes whose identifiers match a regex pattern.

Errors
  • invalid_id_pattern

0..1

delete_archetype (
an_id: ARCHETYPE_ID[1]
)

Pre_artefact_exists: has_artefact (an_id)
Post_archetype_removed: not has_archetype (an_id)

Delete a previously uploaded archetype.

Errors
  • invalid_archetype

1..1

has_opt (
an_opt_id: UUID[1]
): Boolean

Return True if ADL 1.4 OPT with id an_opt_id exists in the service.

1..1

valid_opt (
an_opt: ARCHETYPE[1]
): Boolean

Test validity of OPT an_opt.

0..1

upload_opt (
an_opt: ARCHETYPE[1]
)

Pre_valid: valid_opt(an_opt)

Upload an ADL 1.4 Operational Template (OPT).

Errors:
  • invalid_template

1..1

get_opt (
an_opt_id: UUID[1]
): ARCHETYPE

Get the ADL 1.4 OPT with id an_opt_id.

Errors
  • artefact_does_not_exist

0..1

list_opts (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<UUID>

List all AD 1.4 OPTs known in the service.

0..1

list_matching_opts (
id_pattern: String[1],
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<ARCHETYPE_ID>

List all OPTs whose identifiers match a regex pattern.

Errors
  • invalid_id_pattern

0..1

delete_opt (
an_id: UUID[1]
)

Pre_has_opt: has_opt (an_id)
Post_opt_removed: not has_opt (an_id)

Delete a previously uploaded ADL 1.4. OPT.

Errors
  • invalid_template

1..1

archetypes_count (): Integer

Return total archetypes count.

1..1

opts_count (): Integer

Return total OPTs count.

4.4.3. I_DEFINITION_QUERY Interface

Interface

I_DEFINITION_QUERY

Description

Interface for storying queries and query sets.

Functions

Signature

Meaning

1..1

has_query (
a_query_name: String[1]
): Boolean

Return True if the query identified by a_query_name is registered.

Parameters
a_query_name

Qualified name of query.

1..1

valid_query (
a_query_text: String[1],
a_formalism: String[1]
): Boolean

Return True if the provided query text is a valid instance of the formalism.

1..1

register_query (
a_query_text: String[1],
a_formalism: String[1],
a_query_name: String[0..1]
): QUERY_DESCRIPTOR

Pre_valid_query: is_valid_query(a_query_text)

Register a query under a qualified name. If no name is provided, one is created in the service. Return a Query descriptor containing the query name and unique identifier.

Parameters
a_formalism

Case-insensitive name of the formalism of the query text. Values include "AQL" (and "aql").

1..1

register_query_set (
a_query_set_name: String[0..1]
): UUID

Register a query set.

TODO: determine details.

0..1

list_queries (
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<QUERY_DESCRIPTOR>

List all registered queries.

0..1

list_matching_queries (
id_pattern: String[1],
artefact_id_pattern: String[1],
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<QUERY_DESCRIPTOR>

List all registered queries matching an identifier pattern (regex) and an artefact identifier pattern (regex) for artefacts referenced in the query. Either pattern may be the regex for 'match any'.

Parameters
id_pattern

PERL regular expression on query identifier.

artefact_id_pattern

PERL regular expression on archetype / template identifiers.

Errors
  • invalid_id_pattern

0..1

delete_query (
a_query_name: String[1]
)

Pre_has_query: has_query(a_query_name)
Post_query_deleted: not has_query (a_query_name)

Delete query with name a_query_name.

Parameters
a_query_name

Qualified query name.

Errors
  • invalid_query

1..1

queries_count (): Integer

Return total count of queries.

4.4.4. DEFINITION_CALL_STATUS_TYPE Enumeration

Enumeration

DEFINITION_CALL_STATUS_TYPE

Description

Enumeration representing call statuses for DEFINITION service interface calls.

Attributes

Signature

Meaning

invalid_archetype

An invalid archetype was provided as a parameter.

invalid_template

An invalid template was provided as a parameter.

invalid_artefact

invalid_query

An invalid query was provided as a parameter.

invalid_id_pattern

An invalid archetype identifier regex pattern was provided.

artefact_does_not_exist

A provided archetype identifier does not exist.

template_does_not_exist

A provided template identifier does not exist.

4.4.5. QUERY_DESCRIPTOR Class

Class

QUERY_DESCRIPTOR

Description

Object describing a query in terms of its unique identifier, name under which it is currently registered and registration time under the current name.

Attributes

Signature

Meaning

1..1

qualified_query_name: String

Unique qualified name of query. Qualified names follow patterns such as <namespace>::<query_name>

e.g. "ehr::all_over_50_women".

0..1

version: String

Query semver.org version number.

1..1

registration_time: Iso8601_date_time

Time query was registered in the service.

1..1

formalism: String

Formalism of the query, matching one of:

  • "aql";

  • any other string value.

0..1

source: String

Source query text to be executed (prior to parameter substitution).

5. EHR Service

5.1. Overview

The platform.interface.ehr package shown below defines service interface to the EHR component in the logical platform architecture.

SM platform.interface.ehr
Figure 6. sm.platform.interface.ehr package

5.2. Class Definitions

5.2.1. I_EHR_SERVICE Interface

Interface

I_EHR_SERVICE

Description

Primary interface to EHR_SERVICE persistent repository.

Functions

Signature

Meaning

1..1

has_ehr (
ehr_id: UUID[1]
): Boolean

Return True if a EHR with identifier ehr_id exists.

Parameters
ehr_id

EHR identifier.

1..1

has_ehr_for_subject (
a_subject_id: PARTY_REF[1]
): Boolean

Returns True if there are EHR(s) for a_subject_id.

Parameters
a_subject_id

Subject identifier.

Errors
  • ehr_does_not_exist

1..1

create_ehr (
an_ehr_status: EHR_STATUS[0..1]
): UUID

Pre_no_subject: an_ehr_status.subject = Void
Post_has_ehr: has_ehr (Result)

Create a new EHR with a system-generated identifier and return the id.

If the an_ehr_status parameter is provided, it is created as the EHR’s EHR_STATUS, otherwise a default EHR_STATUS is created, in which is_modifiable and is_queryable are both True.

A default subject will be generating containing a PARTY_SELF object.

1..1

create_ehr_with_id (
an_ehr_id: UUID[1],
an_ehr_status: EHR_STATUS[0..1]
): UUID

Pre_no_subject: an_ehr_status.subject = Void
Pre_no_duplicate: not has_ehr (an_ehr_id)
Post_has_ehr: has_ehr (Result)

Create a new EHR with a provided EHR id; return the id as a safety check.

If the an_ehr_status parameter is provided, it is created as the EHR’s EHR_STATUS, otherwise a default EHR_STATUS is created, in which is_modifiable and is_queryable are both True.

Parameters
an_ehr_id

EHR identifier (a UUID).

Errors
  • ehr_create_fail_duplicate_id

A default subject will be generating containing a PARTY_SELF object.

1..1

create_ehr_for_subject (
a_subject_id: PARTY_REF[1],
an_ehr_status: EHR_STATUS[0..1]
): UUID

Create a new EHR with EHR_STATUS.subject set to point to subject_id, and return its EHR id.

If the an_ehr_status parameter is provided, it is created as the EHR’s EHR_STATUS, otherwise a default EHR_STATUS is created, in which is_modifiable and is_queryable are both True.

Parameters
a_subject_id

Subject identifier.

Errors
  • ehr_for_subject_already_exists

1..1

create_ehr_for_subject_with_id (
an_ehr_id: UUID[1],
a_subject_id: PARTY_REF[1],
an_ehr_status: EHR_STATUS[0..1]
): UUID

Pre_no_duplicate: not has_ehr (an_ehr_id)

Create a new EHR with EHR id and provided subject id. Return the EHR id as a safety check.

If the an_ehr_status parameter is provided, it is created as the EHR’s EHR_STATUS, otherwise a default EHR_STATUS is created, in which is_modifiable and is_queryable are both True.

Parameters
an_ehr_id

EHR identifier (a UUID).

a_subject_id

Subject identifier.

Errors
  • ehr_create_fail_duplicate_id

1..1

get_ehr (
an_ehr_id: UUID[1]
): EHR_SUMMARY

Pre_has_ehr: has_ehr (an_ehr_id)

Retrieve a summarised form of the EHR root object and EHR_STATUS.

Parameters
an_ehr_id

EHR identifier (a UUID).

Errors
  • ehr_id_does_not_exist

0..1

get_ehrs_for_subject (
a_subject_id: PARTY_REF[1]
): List<EHR_SUMMARY>

Retrieve EHR or EHRs that have ehr_status.subject_id = supplied subject id.

Parameters
a_subject_id

Subject identifier.

Errors
  • esubject_id_does_not_exist

1..1

i_ehr (
ehr_id: UUID[1]
): I_EHR

Provide access to an I_EHR interface instance for access to the parts of an EHR.

Errors
  • ehr_id_does_not_exist

5.2.2. I_EHR Interface

Interface

I_EHR

Description

Interface for single patient EHR-level operations.

Attributes

Signature

Meaning

1..1

ehr_status: I_EHR_STATUS

Access to I_EHR_STATUS interface.

1..1

directory: I_EHR_DIRECTORY

Access to I_EHR_DIRECTORY interface.

1..1

compositions: I_EHR_COMPOSITION

Access to I_EHR_COMPOSITION interface.

1..1

contributions: I_EHR_CONTRIBUTION

Access to I_EHR_CONTRIBUTION interface.

5.2.3. I_EHR_STATUS Interface

Interface

I_EHR_STATUS

Description

Interface to EHR_STATUS of an EHR, with implicit Contribution creation.

Functions

Signature

Meaning

1..1

has_ehr_status_version (
an_ehr_id: UUID[1],
a_version_uid: UUID[1]
): Boolean

Pre_has_ehr: has_ehr (an_ehr_id)

True if an_ehr_status_ver_uid is one of the versions of this versioned EHR Status object.

Errors
  • ehr_id_does_not_exist

1..1

get_ehr_status (
an_ehr_id: UUID[1]
): EHR_STATUS

Pre_has_ehr: has_ehr (an_ehr_id)

Get the current version of the EHR_STATUS object for an EHR.

Errors
  • ehr_id_does_not_exist

1..1

get_ehr_status_at_time (
a_time: Iso8601_date_time[0..1]
): EHR_STATUS

Pre_has_ehr: has_ehr (an_ehr_id)

Get the version of the EHR Status extant at time a_time. If no time supplied, get the latest.

Errors
  • ehr_id_does_not_exist

0..1

set_ehr_queryable (
an_ehr_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Post_is_queryable_set: get_ehr_status(an_ehr_id).is_queryable

Set the EHR is_queryable flag to true; this ensures it is included by the query engine.

Errors
  • ehr_id_does_not_exist

0..1

set_ehr_modifiable (
an_ehr_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Post_is_modifiable_set: get_ehr_status(an_ehr_id).is_modifiable

Set the EHR is_modifable flag to true; this ensures it is treated as active and updatable.

Errors
  • ehr_id_does_not_exist

0..1

clear_ehr_queryable (
an_ehr_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Post_is_queryable_cleared: not get_ehr_status(an_ehr_id).is_queryable

Clear the EHR is_queryable flag; this ensures it is ignored by the query engine.

Errors
  • ehr_id_does_not_exist

0..1

clear_ehr_modifiable (
an_ehr_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Post_is_modifiable_cleared: not get_ehr_status(an_ehr_id).is_modifiable

Clear the EHR is_modifiable flag; this ensures it is treated as active.

Errors
  • ehr_id_does_not_exist

0..1

update_other_details (
an_ehr_id: UUID[1],
a_details: ITEM_TREE[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)

Update other_details part of EHR_STATUS with new content.

Errors
  • ehr_id_does_not_exist

1..1

get_ehr_status_at_version (
an_ehr_id: UUID[1],
a_version_uid: UUID[1]
): EHR_STATUS

Pre_has_ehr: has_ehr (an_ehr_id)

Get a particular version of an EHR Status object.

Errors
  • ehr_id_does_not_exist

1..1

get_versioned_ehr_status (
an_ehr_id: UUID[1]
): VERSIONED_EHR_STATUS

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_has_ehr_status_version: has_ehr_status_version (an_ehr_id, a_version_uid)

Get the VERSIONED_EHR_STATUS object from the EHR with id ehr_id.

Errors
  • ehr_id_does_not_exist

5.2.4. I_EHR_DIRECTORY Interface

Interface

I_EHR_DIRECTORY

Description

Operations on EHR directory, with implicit Contribution creation.

Functions

Signature

Meaning

1..1

has_directory (
ehr_id: UUID[1]
): Boolean

Pre_has_ehr: has_ehr (an_ehr_id)

True if the EHR has a directory structure.

1..1

has_path (
ehr_id: UUID[1],
a_path: String[1]
): Boolean

Pre_has_ehr: has_ehr (an_ehr_id)

True if path a_path exists in directory. The a_path argument consists of slash-separated values of the name attribute of Folders in the directory.

Errors
  • ehr_id_does_not_exist

0..1

create_directory (
ehr_id: UUID[1],
a_dir_struct: UV_FOLDER[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_definitions_valid: definitions_valid (a_dir_struct)
Pre_no_directory: not has_directory (ehr_id)
Pre_content_valid: valid_content(a_dir_struct)

Create a directory in the EHR, based on the provided structure. Causes server-side creation of a new VERSIONED_OBJECT, ORIGINAL_VERSION and new CONTRIBUTION.

Errors
  • ehr_id_does_not_exist

  • definition_unknown

  • content_invalid

0..1

get_directory (
ehr_id: UUID[1]
): FOLDER

Pre_has_ehr: has_ehr (an_ehr_id)

Get current version of EHR Directory structure, if it exists, else Void.

Errors
  • ehr_id_does_not_exist

0..1

get_directory_at_time (
an_ehr_id: UUID[1],
a_time: Iso8601_date_time[0..1]
): FOLDER

Pre_has_ehr: has_ehr (an_ehr_id)

Get the version of the Directory extant at time a_time. If no time supplied, get the latest.

Parameters
a_time

Time specifying the extant top version of the Directory.

Errors
  • ehr_id_does_not_exist

0..1

update_directory (
ehr_id: UUID[1],
a_dir_struct: UV_FOLDER[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_definitions_valid: definitions_valid (a_dir_struct)
Pre_content_valid: valid_content(a_dir_struct)
Pre_has_directory: has_directory(ehr_id)

Create or update a directory from a complete structure. Preceding version must be supplied and correct if EHR directory already exists. Causes server-side creation of a new ORIGINAL_VERSION and a new CONTRIBUTION.

Parameters
a_dir_struct

Directory structure with which to replace current structure.

Errors
  • ehr_id_does_not_exist

  • definition_unknown

  • content_invalid

0..1

delete_directory (
ehr_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_has_directory: has_directory(ehr_id)

Logically delete the directory by creating a new version in which the contents are removed.

Errors
  • ehr_id_does_not_exist

1..1

has_directory_version (
an_ehr_id: UUID[1],
a_version_uid: UUID[1]
): Boolean

True if the directory has a version with specified id.

Errors
  • ehr_id_does_not_exist

0..1

get_directory_at_version (
an_ehr_id: UUID[1],
a_version_uid: UUID[1]
): FOLDER

Get a particular version of the EHR Directory.

Errors
  • version_does_not_exist

0..1

get_versioned_directory (
an_ehr_id: UUID[1]
): VERSIONED_FOLDER

Pre_has_ehr: has_ehr (an_ehr_id)

Get the VERSIONED_FOLDER Directory object for the EHR with ehr_id.

Errors
  • ehr_id_does_not_exist

5.2.5. I_EHR_COMPOSITION Interface

Interface

I_EHR_COMPOSITION

Description

Interface for commit and retrieve of Compositions, with implicit Contribution creation.

Functions

Signature

Meaning

1..1

has_composition (
an_ehr_id: UUID[1],
a_version_uid: OBJECT_VERSION_ID[1]
): Boolean

Pre_has_ehr: has_ehr (an_ehr_id)

Return True if a Composition version with identifier a_version_uid exists.

Errors
  • ehr_id_does_not_exist

1..1

get_composition_latest (
an_ehr_id: UUID[1],
a_versioned_object_uid: UUID[1]
): COMPOSITION

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_has_composition: has_composition (an_ehr_id, a_version_uid)

Retrieve the latest version of a Composition.

Parameters
a_versioned_object_uid

Uid of the VERSIONED_COMPOSITION.

Errors
  • ehr_id_does_not_exist

  • composition_does_not_exist

1..1

get_composition_at_time (
an_ehr_id: UUID[1],
a_versioned_object_uid: UUID[1],
a_time: Iso8601_date_time[0..1]
): COMPOSITION

Pre_has_ehr: has_ehr (an_ehr_id)

Retrieve the Composition version extant at a given time, from a Versioned Composition. If no time supplied, get the latest.

Errors
  • ehr_id_does_not_exist

  • composition_does_not_exist

1..1

get_composition_at_version (
an_ehr_id: UUID[1],
a_version_uid: OBJECT_VERSION_ID[1]
): COMPOSITION

Get a particular Version of a Composition by version id.

Errors
  • ehr_does_not_exist

  • object_version_does_not_exist

1..1

get_versioned_composition (
an_ehr_id: UUID[1],
a_versioned_object_uid: UUID[1]
): VERSIONED_COMPOSITION

Pre_has_ehr: has_ehr (an_ehr_id)

Retrieve the VERSIONED_OBJECT of a Composition by uid.

Errors
  • ehr_id_does_not_exist

  • versioned_composition_does_not_exist

1..1

create_composition (
an_ehr_id: UUID[1],
a_comp: UV_COMPOSITION[1]
): UUID

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_composition_definitions_valid: definitions_valid (a_comp)
Pre_content_valid: valid_content (a_comp)
Post_has_composition: has_composition (an_ehr_id, Result)

Create the first version of a new Composition. Causes server-side creation of a new VERSIONED_OBJECT, ORIGINAL_VERSION and new CONTRIBUTION.

Errors
  • ehr_id_does_not_exist

  • composition_already_exists

  • definition_unknown

  • content_invalid

1..1

update_composition (
an_ehr_id: UUID[1],
a_comp: UV_COMPOSITION[1]
): UUID

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_composition_definitions_valid: definitions_valid (a_comp)
Pre_content_valid: valid_content (a_comp)

Update an existing Composition, which includes server-side creation of a new ORIGINAL_VERSION and a new CONTRIBUTION.

Errors
  • ehr_id_does_not_exist

  • composition_does_not_exist

  • definition_unknown

  • content_invalid

0..1

delete_composition (
an_ehr_id: UUID[1],
a_version_uid: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)

Logically delete a Composition by creating a new version in which the content is removed and the lifecycle state is set to 523|deleted|. The a_version_uid argument identifies the current top Composition Version.

Errors
  • ehr_id_does_not_exist

  • composition_does_not_exist

5.2.6. I_EHR_CONTRIBUTION Interface

Interface

I_EHR_CONTRIBUTION

Description

Interface for explicit Contribution level operations.

Functions

Signature

Meaning

0..1

has_contribution (
an_ehr_id: UUID[1],
a_contrib_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)

Return True if the Contribution with a_contrib_id in EHR with id an_ehr_id exists.

Errors
  • ehr_id_does_not_exist

1..1

get_contribution (
an_ehr_id: UUID[1],
a_contrib_id: UUID[1]
): CONTRIBUTION

Pre_has_ehr: has_ehr (an_ehr_id)
Pre_has_contribution: has_contribution (a_contrib_id)

Return the Contribution with id a_contrib_id in EHR with id an_ehr_id.

Errors
  • ehr_id_does_not_exist

  • contribution_does_not_exist

1..1

commit_contribution (
an_ehr_id: UUID[1],
versions: List<UPDATE_VERSION>[1],
an_audit: UPDATE_AUDIT[1]
): UUID

Pre_has_ehr: has_ehr (an_ehr_id)
Post_has_contribution: has_contribution (a_contrib_id)

Commit a CONTRIBUTION containing any number of UPDATE_VERSION objects.

Errors
  • ehr_id_does_not_exist

0..1

list_contributions (
an_ehr_id: UUID[1],
time_range: Interval<Iso8601_date_time>[0..1],
item_offset: Integer[0..1],
items_to_fetch: Integer[0..1]
): List<UUID>

Obtain a list of identifiers of Contributions in EHR.

Parameters
time_range

Optional time range to limit Contributions to.

Errors
  • ehr_does_not_exist

1..1

contribution_count (
ehr_id: UUID[1],
time_range: Interval<Iso8601_date_time>[0..1]
): Integer

Obtain a count of Contributions in EHR.

Parameters
ehr_id

EHR identifier (Guid).

time_range

Optional time range to limit Contributions count to.

Errors
  • ehr_does_not_exist

5.2.7. EHR_SUMMARY Class

Class

EHR_SUMMARY

Description

Summary form of EHR + EHR_STATUS objects convenient for use in service interface.

Attributes

Signature

Meaning

1..1

ehr_id: UUID

EHR identifier of this EHR.

1..1

system_id: String

Copy of EHR.system_id.

1..1

ehr_status: EHR_STATUS

Copy of EHR.ehr_status.

1..1

time_created: Iso8601_date_time

Copy of EHR.time_created.

1..1

contribution_count: Integer

Number of Contributions in this EHR.

1..1

composition_count: Integer

Number of (versioned) Compositions in this EHR.

6. Demographic Service

6.1. Overview

The platform.interface.demographic package shown below defines service interface to the DEMOGRAPHIC_SERVICE component in the logical platform architecture.

SM platform.interface.demographic
Figure 7. sm.platform.interface.demographic package

6.2. Class Definitions

6.2.1. I_DEMOGRAPHIC_SERVICE Interface

Interface

I_DEMOGRAPHIC_SERVICE

Description

Primary interface to DEMOGRAPHIC_SERVICE.

Functions

Signature

Meaning

1..1

create_party (
a_version: UV_PARTY[1]
): UUID

Pre_party_definitions_valid: definitions_valid (a_version)
Pre_content_valid: valid_content (a_version)

Create the first version of a new PARTY object. Causes server-side creation of a new VERSIONED_OBJECT, ORIGINAL_VERSION and new CONTRIBUTION.

Errors
  • definition_unknown

  • content_invalid

1..1

create_party_relationship (
a_version: UV_PARTY_RELATIONSHIP[1]
): UUID

Pre_content_valid: valid_content (a_version)

Create the first version of a new PARTY_RELATIONSHIP. Causes server-side creation of a new VERSIONED_OBJECT, ORIGINAL_VERSION and new CONTRIBUTION.

Errors
  • definition_unknown

  • content_invalid

1..1

i_party (
a_versioned_party_id
): I_PARTY

Create an I_PARTY interface.

Errors
  • versioned_object_does_not_exist

1..1

i_party_relationship (
a_versioned_party_rel_id
): I_PARTY_RELATIONSHIP

Create an I_PARTY_RELATIONSHIP interface.

Errors
  • versioned_object_does_not_exist

6.2.2. I_PARTY Interface

Interface

I_PARTY

Description

Interface for PARTY level operations.

Functions

Signature

Meaning

1..1

has_party (
a_versioned_party_id: UUID[1]
): Boolean

Return True if Party exists.

1..1

has_party_version_id (
a_party_version_id: UUID[1]
): Boolean

True if a particular version of a Party exists.

1..1

get_party (
a_versioned_party_id: UUID[1]
): PARTY

Pre_has_party: has_party (a_versioned_party_id)

Get the current Version of a Party.

Errors
  • versioned_object_does_not_exist

1..1

get_party_at_time (
a_versioned_party_id: UUID[1],
a_time: Iso8601_date_time[1]
): PARTY

Get the Version of a Party current at a_time.

Errors
  • versioned_object_does_not_exist

1..1

update_party (
a_versioned_party_id: UUID[1],
a_version: UV_PARTY[1]
): UUID

Pre_party_definitions_valid: definitions_valid (a_version)
Pre_has_party: has_party (a_versioned_party_id)

Update a PARTY with a new Version. Causes server-side creation of a new ORIGINAL_VERSION and CONTRIBUTION.

Errors
  • versioned_object_does_not_exist

  • object_version_does_not_exist

  • definition_unknown

  • content_invalid

0..1

delete_party (
a_versioned_party_id: UUID[1]
)

Pre_has_party: has_party (a_versioned_party_id)
Post_party_deleted: not has_party (a_versioned_party_id)

Delete an existing Party.

Errors
  • versioned_object_does_not_exist

1..1

get_party_at_version (
a_party_version_id: UUID[1]
): PARTY

Pre_has_party_version: has_party_version (a_party_version_id)

Get a particular Party Version.

Errors
  • object_version_does_not_exist

6.2.3. I_PARTY_RELATIONSHIP Interface

Interface

I_PARTY_RELATIONSHIP

Description

Interface for PARTY_RELATIONSHIP operations.

Functions

Signature

Meaning

1..1

has_party_relationship (
a_versioned_party_rel_id: UUID[1]
): Boolean

Return True if Party relationship exists in service.

1..1

get_party_relationship (
a_versioned_party_rel_id: UUID[1]
): PARTY_RELATIONSHIP

Get the current Version of a Party relationship.

Errors
  • versioned_object_does_not_exist

1..1

get_party_relationship_at_time (
a_versioned_party_rel_id: UUID[1],
a_time: Iso8601_date_time[1]
): PARTY_RELATIONSHIP

Get the Version of a Party relationship current at a_time.

Errors
  • versioned_object_does_not_exist

1..1

update_party_relationship (
a_versioned_party_rel_id: UUID[1],
a_version: UV_PARTY_RELATIONSHIP[1]
): UUID

Pre_party_definitions_valid: definitions_valid (a_version)
Pre_has_relationship: has_party_relationship (a_versioned_party_rel_id)

Update a PARTY_RELATIONSHIP with a new Version. Causes server-side creation of a new ORIGINAL_VERSION and CONTRIBUTION.

Errors
  • versioned_object_does_not_exist

  • object_version_does_not_exist

  • definition_unknown

  • content_invalid

0..1

delete_party_relationship (
a_versioned_party_rel_id: UUID[1]
)

Pre_has_relationship: has_party_relationship (a_versioned_party_rel_id)
Post_relationship_deleted: not has_party_relationship (a_versioned_party_rel_id)

Delete an existing Party relationship.

Errors
  • versioned_object_does_not_exist

1..1

get_party_relationship_at_version (
a_party_rel_version_id: UUID[1]
): PARTY_RELATIONSHIP

Get a particular Party relationship Version.

Errors
  • object_version_does_not_exist

7. EHR Index Service

7.1. Overview

The platform.interface.ehr_index package shown below defines service interface to the EHR_INDEX component in the logical platform architecture.

SM platform.interface.ehr index
Figure 8. sm.platform.interface.ehr_index package

The primary function of the EHR Index service is to enable the recording of associations of subject identifiers (i.e. patient or other subject or care identifiers) with EHR identifiers. In a privacy-supporting environment, this enables EHRs to be persisted with only an EHR id; the EHR Index has to be used to obtain the subject identifier, which will usually be used as a key into a demographic or MPI service, ultimately allowing EHR data to be associated with the correct patient demographic information in a user application.

There is no limit on the number of subject identifiers associated with a given EHR id, and vice versa, since in real environments both situations commonly occur. The two cases are as follows:

  • multiple subject identifiers for one EHR id: indicates that more than one subject of care has data in the same EHR. This is a dangerous error condition, and needs to be detected and rectified.

  • multiple EHR ids for a given subject identifier: indicates that multiple EHRs have been created for the same subject, typically as a result of name entry errors, and / or of multiple departments independently creating EHRs rather than locating existing ones for the patient. This is also an error situation, although less dangerous than the inverse situation.

To enable management of these problems, other meta-data can be associated with each EHR id / subject id association, represented by the RESOURCE_STATUS type.

A further useful facility that can be provided by this service is to maintain dynamic location information for EHRs. This is enabled by the inclusion of optional LOCATION_DESC instances with index records.

7.2. Class Definitions

7.2.1. I_EHR_INDEX Interface

Interface

I_EHR_INDEX

Description

Interface object for the EHR_INDEX service.

Functions

Signature

Meaning

0..1

add_ehr_subject (
an_ehr_id: UUID[1],
a_subject_id: OBJECT_REF[1],
a_status: RESOURCE_STATUS[0..1],
a_loc_desc: LOCATION_DESC[0..1]
)

Add a subject identifier for the EHR with an_ehr_id, with an optional resource status and location descriptor.

0..1

update_ehr_subject_status (
an_ehr_id: UUID[1],
a_subject_id: OBJECT_REF[1],
a_status: RESOURCE_STATUS[1]
)

Update subject resource status for the association of the EHR with an_ehr_id and subject a_subject_id.

Errors
  • subject_id_does_not_exist

  • ehr_id_does_not_exist

0..1

update_ehr_subject_loc_desc (
an_ehr_id: UUID[1],
a_subject_id: OBJECT_REF[1],
a_loc_desc: LOCATION_DESC[0..1]
)

Update location descriptor for the association of the EHR with an_ehr_id and subject a_subject_id.

Errors
  • subject_id_does_not_exist

  • ehr_id_does_not_exist

0..1

remove_ehr_subject (
an_ehr_id: UUID[1],
a_subject_id: OBJECT_REF[1]
)

Remove the subject identifier association with the EHR with an_ehr_id (it might remain associated with other EHRs however).

Errors
  • subject_id_does_not_exist

  • ehr_id_does_not_exist

0..1

remove_subject (
a_subject_id: OBJECT_REF[1]
)

Remove all entries for a subject.

Errors
  • subject_id_does_not_exist

7.2.2. RESOURCE_STATUS Class

Class

RESOURCE_STATUS

Description

Object describing the status of a reference to a resource.

Attributes

Signature

Meaning

1..1

instance_type: RESOURCE_INSTANCE_TYPE

Type of resource instance.

0..1

start_valid_time: @@

First time point at which resource can be assumed to be available.

0..1

end_valid_time: @@

Last time point at which resource can be assumed to be available.

0..1

notes: String

Human-readable notes on the resource.

7.2.3. RESOURCE_INSTANCE_TYPE Enumeration

Enumeration

RESOURCE_INSTANCE_TYPE

Description

Enumeration of resource instance types.

Attributes

Signature

Meaning

Primary

Primary instance of the resource.

Duplicate

A duplicate instance of the resource.

Supplementary

7.2.4. LOCATION_DESC Class

Class

LOCATION_DESC

Description

A descriptor containing location information for the EHR with which this descriptor is associated.

8. Query Service

8.1. Overview

The platform.interface.query package shown below defines service interface to the QUERY_SERVICE component in the logical platform architecture.

SM platform.interface.query
Figure 9. sm.platform.interface.query package

The model of querying here is based on the notion of being able to execute either queries previously stored in the DEFINITION service, or else ad hoc queries. For stored queries, no assumption is made as to whether the query language is AQL (the openEHR default) or something else, only that there are stored queries that can be executed in a standard way.

For both kinds of queries, parameters must be provided for open parameters in the stored query.

If either type of query executes successfully, the response is a RESULT_SET, which consists of meta-data, a column definition structure and a set of rows (instances of RESULT_SET_ROW). In order to handle large result sets efficiently and gracefully within applications, the parameters item_offset and items_to_fetch can be provided to control the result size.

A stored query is identified by the identifier associated with it when registered in the DEFINITION service, which is ofthe form:

    reverse-domain-name '::' semantic-id [ '/' version ]

For example: org.example.departmentx.test::diabetes-patient-overview/1.0.2. The optional version enables multiple forms of the same semantic query to co-exist in the service.

8.2. Class Definitions

8.2.1. I_QUERY_SERVICE Interface

Interface

I_QUERY_SERVICE

Description

Query execution service interface.

Functions

Signature

Meaning

0..1

execute_stored_query (
exec_spec: STORED_QUERY_EXECUTE_SPEC[1],
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1],
ehr_ids: List<UUID>[0..1]
): RESULT_SET

Execute a query stored in the definition service, using its qualified query name. Return a Result set.

Parameters
exec_spec

Execution specification: which query and optional version to execute, with provided parameters.

row_offset

Optional parameter specifying offset in query response rows to return, used for large result sets. A zero or negative value means offset of zero.

rows_to_fetch

Optional parameter specifying number of query response rows to fetch, used for large result sets. A zero or negative value means 'all'.

ehr_ids

Specific set of EHRs on which to execute the query. If none supplied, a full population query will be performed on all EHRs whose status has the is_queryable flag set to True.

Errors
  • ehr_id_does_not_exist

0..1

execute_ad_hoc_query (
exec_spec: ADHOC_QUERY_EXECUTE_SPEC[1],
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1],
ehr_ids: List<UUID>[0..1]
): RESULT_SET

Execute an ad hoc query, supplying the query text.

Parameters
exec_spec

Execution specification: query text to execute, with provided parameters.

row_offset

Optional parameter specifying offset in query response rows to return, used for large result sets. A zero or negative value means offset of zero.

rows_to_fetch

Optional parameter specifying number of query response rows to fetch, used for large result sets. A zero or negative value means 'all'.

ehr_ids

Specific set of EHRs on which to execute the query. If none supplied, a full population query will be performed on all EHRs whose status has the is_queryable flag set to True.

Errors
  • ehr_id_does_not_exist

8.2.2. STORED_QUERY_EXECUTE_SPEC Class

Class

STORED_QUERY_EXECUTE_SPEC

Description

Class representing query execution specification for stored queries, including name, parameters (where applicable) and optional version.

Attributes

Signature

Meaning

1..1

qualified_query_name: String

Qualified name of query, which is of the form reverse_domain::name.

0..1

version: String

If supplied, version of the query to execute specified as a semver.org 3-part string. If not supplied, the latest version available will be executed.

1..1

query_parameters: Hash<String, String>

Parameters to substitute in query in the form of a set of tagged String values; each tag must match a parameter name in the query.

8.2.3. ADHOC_QUERY_EXECUTE_SPEC Class

Class

ADHOC_QUERY_EXECUTE_SPEC

Description

Class representing query execution specification for ad hoc queries, including query text and parameters (where applicable).

Attributes

Signature

Meaning

1..1

source: String

AQL text of query.

0..1

formalism: String
{default = "aql"}

1..1

query_parameters: Hash<String, String>

Parameters to substitute in query in the form of a set of tagged String values; each tag must match a parameter name in the query.

8.2.4. RESULT_SET Class

Class

RESULT_SET

Description

Structured query execution result. The columns attribute contains a definition of columns, while the result data is represented by the rows attribute.

Ideally the Result set has sufficient meta-data to be processible independently of the original query.

Inherit

Any

Attributes

Signature

Meaning

1..1

columns: List<RESULT_SET_COLUMN>

Column definition structure.

1..1

id: String

Unique identifier of this result set.

1..1

creation_time: Iso8601_date_time

Time of creation of this Result set by execution engine.

0..1

query: RESULT_QUERY_DESCRIPTOR

0..1

rows: List<RESULT_SET_ROW>

Rox data.

8.2.5. RESULT_SET_COLUMN Class

Class

RESULT_SET_COLUMN

Description

Query column definition.

Attributes

Signature

Meaning

1..1

name: String

Column name for caller to use.

0..1

archetype_id: String

Note
check on whether needed or inside the path.

0..1

path: String

RM path of data item for this column as specified in query.

8.2.6. RESULT_SET_ROW Class

Class

RESULT_SET_ROW

Description

Structure representing a single row of output from an executed query.

Attributes

Signature

Meaning

0..1

values: List<Any>

List of items corresponding to the columns of the owning Result set.

9. Message Service

9.1. Overview

The platform.interface.message package shown below defines service interface to the MESSAGE component in the logical platform architecture.

SM platform.interface.message
Figure 10. sm.platform.interface.message package

9.2. Class Definitions

9.2.1. I_MESSAGE_SERVICE Interface

Interface

I_MESSAGE_SERVICE

Description

Generic message service.

9.2.2. I_EHR_EXTRACT_SERVICE Interface

Interface

I_EHR_EXTRACT_SERVICE

Description

EHR Extract service; provides interface for importing and exporting EHR_EXTRACTs as defined by the openEHR EHR Extract specification.

Functions

Signature

Meaning

0..1

export_ehrs (
an_ehr_id: UUID[1]
): List<EXTRACT>

Export whole EHR for one or more subjects.

0..1

export_ehr_extracts (
extract_spec: EXTRACT_SPEC[1]
): List<EXTRACT>

Export an extract for one or more EHRs.

0..1

import_ehr (
an_ehr_id: UUID[0..1],
an_extract: EXTRACT[1]
)

Import a whole EHR, optionally providing a fixed EHR identifier, which, usually to match the identifier of EHR(s) for the same patient in other EHR services.

0..1

import_ehr_extract (
an_ehr_id: UUID[1],
an_extract: EXTRACT[1]
)

Import an EHR Extract into an existing EHR.

9.2.3. I_TDD_SERVICE Interface

Interface

I_TDD_SERVICE

Description

Template Data Document (TDD) service.

Functions

Signature

Meaning

0..1

import_tdd (
an_ehr_id: UUID[1],
tdd: String[1]
)

Import a TDD.

0..1

import_tdds

Bulk import numerous TDDs.

10. Subject Proxy Service

10.1. Conceptual Purpose

The Subject Proxy Service performs a number of jobs, which taken together, have the effect of 'lifting' data from the typically complex IT environment, and converting it to a clean representation of specific subject attributes relevant to specific applications, including Plan workflows and Decision Support. These jobs are described below.

10.1.1. Semantic Reframing: from the General and Epistemic to the Ontic and Use-specific

The relationship between guidelines and data exhibits a number of semantic characteristics that lead to the concept of the Subject Proxy as an independent interfacing service.

In order to define a care pathway or guideline (possibly adapted into a patient-specific care plan), various subject state variables and events are needed. Since guidelines are specific to purpose, the number of variables is typically low, and for many simpler guidelines, as few as three or four. Many guidelines need access to common variables such as 'sex', 'age', basic clinical classifiers such as 'is diabetic', 'is pregnant' and then a relatively small number of condition-specific variables representing patient state (e.g. 'neutrophils', 'ldl') and specific diagnoses (e.g. 'eclampsia', 'gestational hypertension'). A guideline of medium complexity, such as for RCHOPS (non-Hodgkins lymphoma) chemotherapy needs around 20 variables, and a complex guideline such as for sepsis might need 50 - 100.

These small numbers are in contrast to the total number of distinct types of data point that will be routinely recorded for an average subject over long periods and relating to all conditions, which is in the O(1k) range, or the number of such data points recorded for a population, e.g. all inpatients + outpatients of a large hospital, which is O(10k). The latter corresponds to the variety of data that a general EMR product would need to cope with. The 'data sets' for specific guidelines are thus small and well-defined in comparison to the data generally captured within a patient record over time, and thus candidates for encapsulation.

Data set size is not the only distinguishing characteristic of a computable guideline. Where variables such as 'systolic blood pressure', 'is diabetic' and so on are mentioned in guidelines, they are intended to refer to the real patient state or history, i.e. they are references to values representing ontic entities, independent of how they might be obtained or stored. This is in contrast with the view of data where it is captured in health records or documents, which is an epistemic one, i.e. the result of a knowledge capture activity. Consequently, a query into a departmental hospital system asking if patient 150009 is diabetic, indicates that the patient is diabetic in the case of a positive answer, but otherwise probably doesn’t indicate anything, since the full list of patient 150009’s problems is often not found in departmental systems.

A query into any particular epistemic resource, i.e. a particular database, health record system or document only indicates what is known about the subject by that system. A true picture of the patient state can be approximated by access to all available data stores (e.g. hospital and GP EMR systems), assuming some are of reasonable quality, and is further improved by access to real-time device data (e.g. monitors connected to the patient while in hospital, but also at home). The best approximation of the ontic situation of the patient will be from the sum of all such sources plus 'carers in the room' who can report events as they unfold (patient going into cardiac arrest), and the patient herself, who is sometimes the only reliable origin of certain facts.

This epistemic coverage problem indicates a need which may be addressed with the Subject Proxy, which is to act as a data 'concentrator', obtaining relevant data from all epistemic sources including live actors to obtain a usable approximation of true patient state. This is a practical thing to do at the guideline / plan level by virtue of the small sizes of the variable sets. The data concentrator function is described in more detail below.

Comprehensive coverage of all possible sources is not the only problem to solve in order to define variables for use in guidelines and plans. In formal terms, symbolic references appearing at different levels in the environment have different semantics. Within the EHR system S1 for example, a generic API call has_diagnosis(pat_id, x) has the meaning: 'indicates whether patient P is known to have diagnosis x, according to S1'. However, within a guideline related to pregnancy, a variable is_diabetic defined in a Subject Proxy is more convenient, and is intended to represent the true diabetic state (or not) of the patient. The SPO thus not only has the effect of data concentration in order to extract a true ontic picture of the subject, but it reifies technical data access calls into ontic variables, specific to the guideline. In some cases, such variables might have pre-coordinated names such as previous_history_of_eclampsia, combining a temporal region with a substantive state.

10.1.2. Manually Reported and Missing Data

A Subject Proxy acts as a data concentrator, providing a single interface to all available sources of information about the subject. In a typical in-patient or live-encounter (e.g. GP visit) situation, these include:

  • the EMR system providing the institutional patient record;

  • any shared (e.g. regional or national) EHR system providing e.g. summary and/or emergency data;

  • devices attached to the patient, e.g. vital signs, pulse oximeter etc.

In many cases, a variable required by an application, e.g. sufficiently recent patient weight, is not available from the EMR/EHR or from any other source. This is a common problem in all decision support environments, and the usual solution is that an application window is displayed to ask the clinician for the data directly. This may be entered (e.g. after weighing the patient or asking the patient for his last weight), saved into the EMR, and the original request retried. Traditionally, this data request 'loop' has been engineered into either the main EMR application or into the decision support component. It is however a general problem and can be conveniently solved in a generic way using the Subject Proxy.

Further, there are some subject state variables and particularly events that are only available 'live' from clinicians working with the patient, e.g. state of consciousness, occurrence of a post-heart surgery heart attack (requiring emergency cardiac shock and/or re-sternotomy), haemorrhage during childbirth etc. Such events can only be realistically asserted 'in the room' by a clinician, potentially via a voice interface.

Consequently, we can say that the following constitute two more routine data sources for a Subject Proxy:

  • just-in-time UI capture of missing data;

  • manually-reported events 'in the room'.

The effect of data concentration in the Subject Proxy is that the plan, decision support, and all other applications can rely on a single location to obtain patient state and events, even where the relevant underlying data are not (yet) available in source systems. Additionally, such 'live' data obtained by sich methods may be written to the relevant EMR and/or EHR by the Subject Proxy, removing the problem of other applications having to make ad hoc writes, following ad hoc data capture.

10.1.3. Type Conversion

A natural consequence of obtaining data from multiple sources is that the data will be instances different concrete concrete models (e.g. HL7 messages, documents and FHIR resources; openEHR query results; proprietary EMR data etc). It is also the case that the requesting plan-oriented and decision-support applications can work effectively with a relatively stripped down system of data types and limited structures. The latter is due to the fact that although data tend to be captured in larger structures such as full blood panels, full vital sign data sets and so on, guidelines and plans tend to require only specific lab analytes (e.g. troponin for investigating possible heart attack) and vital signs, e.g. systolic blood pressure (no need for diastolic pressure, patient position or other details).

The consequence of this is that the type system required at the Subject Proxy level may be significantly simplified compared to the type systems and structures in which data are originally captured. The use of an SPO as the interface for decision support and plan applications to back-end systems greatly simplifies the artifacts needed in the latter components.

10.1.4. The Temporal Dimension: Currency

Another common problem traditionally handled by individual applications, including decision-support, is the currency of data, i.e. its 'recency'. Some variables such as body height are sufficiently current even when measured years earlier, while others such as oxygen saturation and heart rate need to be less than a minute old to be useful. To obtain valid values, applications often implement a scheme based on polling, automated server-side 'push' query execution, publish-subscribe or other mechanisms to obtain current data. None of this funcionality can really be avoided, but the Subject Proxy provides a single place to locate it, such that client applications simply access the SPO variables they need, and the SPO takes care of the update problem.

10.2. Service Model

The platform.interface.subject_proxy package shown below defines the service interface and related information structures for the SUBJECT_PROXY service in the openEHR platform architecture. This service allows real world variables characterising the state of a subject, which is usually a patient, but may be some other entity, to be tracked over time. The subject is registered in the service.

SM platform.interface.subject proxy
Figure 11. sm.platform.interface.subject_proxy package

10.2.1. Class Descriptions

10.2.1.1. I_SUBJECT_PROXY_SERVICE Interface

Interface

I_SUBJECT_PROXY_SERVICE

Description

Service that maintains subject 'proxies' consisting of variables, and also enables applications to associate data-sets with subject variables.

Functions

Signature

Meaning

0..1

register_subject (
subject_id: String[1],
subject_category: String[0..1]
)

Pre_subject_valid: not has_subject(subject_id)

Register a new subject. The subject category may also be specified, otherwise it will be the default category.

0..1

add_subject_variable (
subject_id: String[1],
var: SUBJECT_VARIABLE[1]
)

Pre_subject_valid: has_subject(subject_id)

Add a new subject variable definition to the proxy for subject_id.

0..1

register_binding (
binding: ENV_BINDING[1]
)

Pre_new_env: not has_binding(binding.env_id)

Register a binding for an environment, consisting of a set of variable bindings, each including method(s) for data retrieval to populate the related variable

0..1

add_binding_variable (
env_id: String[1],
var: VARIABLE_BINDING[1]
)

Pre_valid_binding: has_binding(env_id)

Add a variable binding to the binding for an environment.

0..1

register_application_data_set (
definition: SUBJECT_DATA_SET[1]
)

Register a data-set consisting of a set of subject variable for an existing subject by an application.

This may have the effect of creating new subject variables, reducing the currency of existing subject variables, if the currency is lower in the corresponding data set variable, or making no change for variables that already exist.

0..1

remove_application_data_set (
subject_id: String[1],
application_id: String[1]
)

Pre_subject_valid: has_subject(subject_id)
Pre_application_valid: has_application(application_id)

Remove this data-set from the service.

0..1

remove_subject (
subject_id: String[1]
)

Pre_subject_valid: has_subject(subject_id)

Remove proxy and any data-sets for an existing subject.

0..1

remove_application (
application_id: String[1]
)

Pre_application_valid: has_application(application_id)

Remove all data-sets for application_id, across all subjects.

1..1

get_variable (
subject_id: String[1],
var_name: String[1]
): VARIABLE_VALUE

Pre_subject_valid: has_subject(subject_id)

Get a single variable value from a data-set.

1..1

get_data_set (
subject_id: String[1],
data_set_id: String[1]
): DATA_SET_RESULT

Pre_subject_valid: has_subject(subject_id)

Get a full data set result.

1..1

has_subject (
subject_id: String[1]
): Boolean

Return True if subject with id subject_id has been registered in the service.

1..1

has_application (
application_id: String[1]
): Boolean

Return True if application with id application_id has been registered in the service.

1..1

has_binding (
env_id: String[1]
): Boolean

Return True if evironment binding with id env_id has been registered in the service.

10.3. Data Structures

The data structures used by the Subject Proxy Service are shown below.

SM platform.interface.subject proxy structure
Figure 12. Subject Proxy structures

10.3.1. Class Definitions

10.3.1.1. SUBJECT_PROXY Class

Class

SUBJECT_PROXY

Description

Proxy object for subject identified by subject_id. The variables attribute is the full set of proxy variables being retrieved for this subject.

Attributes

Signature

Meaning

1..1

subject_id: String

Identifier of data subject, i.e. the entity for which the variables 'are about'.

0..1

variables: Hash<String,SUBJECT_VARIABLE>

The proxy variables for this subject.

1..1

create_time: Iso8601_date_time

Time of creation of this proxy.

1..1

subject_category: String

Category of subject, e.g. patient, other entity.

TODO: currently not controlled.

0..1

data_sets: List<SUBJECT_DATA_SET>

All data sets for this subject.

10.3.1.2. SUBJECT_VARIABLE Class

Class

SUBJECT_VARIABLE

Description

A single subject variable whose data may take various forms, including atomic, list and time series.

Attributes

Signature

Meaning

0..1

source: I_DATA_BINDING

Source data frame, derived from source_frame_id. In an optimised system, may be shared with Data set items from other Data sets.

0..1

history: List<VARIABLE_SAMPLE>

Samples constituting the retrieve history of this variable.

0..1

last_result: RESULT_SET_SAMPLE

Most recently obtained result.

1..1

name: String

Symbolic name by which this item is known in the data-set. Typically required to be a legal variable name in a programming language.

1..1

type_name: String

Formal type name from defining model.

0..1

currency: Iso8601_duration

Required currency of this data item. If not set, most recent available is valid.

0..1

ask_user: Boolean

If set true, the service should attempt to obtain the data item from a live user.

TODO: can only work if access method defined.

1..1

is_manual: Boolean

True if this variable is obtained by manual notification, typically from a worker observing the subject in a point of care situation.

Functions

Signature

Meaning

1..1

value (): VARIABLE_SAMPLE

Extract the value from the source retrieve frame, reprocessing if necessary to obtain intended type (single, list, time_series).

10.3.1.3. SUBJECT_DATA_SET Class

Class

SUBJECT_DATA_SET

Description

Data set relating to a subject as used within an application.

Attributes

Signature

Meaning

1..1

name: String

Unique name of this data set.

1..1

subject_id: String

Identifier of data subject, i.e. the entity for which these data 'are about'.

0..1

creating_app_id: String

Identifier of creating / registering application.

0..1

using_app_ids: List<String>

Optional list of identifiers of applications using this data set. May be used to track applications, and dump the data set when empty.

1..1

variables: Hash<String,SUBJECT_VARIABLE>

Set of variable definitions in this data set.

0..1

last_result: DATA_SET_RESULT

Most recently obtained data set result.

Functions

Signature

Meaning

1..1

value (): DATA_SET_RESULT

Iterate over all variables and generate a DATA_SET_RESULT.

10.3.1.4. DATA_SET_RESULT Class

Class

DATA_SET_RESULT

Description

Data set result consisting of full set of variable values extracted from data retrieve frame sources.

Attributes

Signature

Meaning

1..1

name: String

Unique name of this data set.

1..1

subject_id: String

Identifier of data subject, i.e. the entity for which these data 'are about'.

0..1

variables: List<VARIABLE_SAMPLE>

Samples of variables included in this data set.

10.3.1.5. SAMPLE Class

Class

SAMPLE<T>

Description

One retrieval (sample) of a data 'block', generated by invocation of some retrieval method. The concept of a 'sample' encompasses retrieval (attempt) time-stamp, availability status, and result, if available. Every retrieval attempt will generate a new Sample object, regardless of whether data was actually available or not.

Attributes

Signature

Meaning

1..1

retrieve_time: Iso8601_date_time

Time at which data retrieve attempt made (i.e. when data frame instantiated on caller side, if successful).

0..1

effective_time: Iso8601_date_time

Real-world time to which data pertains, if available. Usually obtainable via model-specific call.

1..1

is_unavailable: Boolean

Flag to indicate that no data available for this retrieve attempt.

0..1

unavailable_reason: String

Potentially a reason for absent data on this retrieve.

0..1

result: T

Result of retrieve call execution.

10.3.1.6. RESULT_SET_SAMPLE Class

Class

RESULT_SET_SAMPLE

Description

Sample whose result is in the form of a RESULT_SET structure.

Inherit

SAMPLE

Attributes

Signature

Meaning

0..1
(redefined)

result: RESULT_SET

Result of retrieve call execution.

10.3.1.7. VARIABLE_SAMPLE Class

Class

VARIABLE_SAMPLE

Description

Sample whose result is in the form of a VARIABLE_VALUE (descendant) structure.

Inherit

SAMPLE

Attributes

Signature

Meaning

0..1
(redefined)

result: VARIABLE_VALUE

Result of retrieve call execution.

10.3.1.8. VARIABLE_VALUE Class

Class

VARIABLE_VALUE (abstract)

Description

Abstract parent of variable value structures.

Inherit

Any

10.3.1.9. VARIABLE_VALUE_SINGLE Class

Class

VARIABLE_VALUE_SINGLE

Description

Atomic Variable value.

Inherit

VARIABLE_VALUE

Attributes

Signature

Meaning

0..1

value: Any

Single value, copied or referenced from the Result set of the latest sample of the relevant source Data retrieve frame.

10.3.1.10. VARIABLE_VALUE_LIST Class

Class

VARIABLE_VALUE_LIST

Description

Variable value in the form of a list.

Inherit

VARIABLE_VALUE

Attributes

Signature

Meaning

0..1

value: List<Any>

Single value, copied or referenced from the Result set of the latest sample of the relevant source Data retrieve frame.

May require transformation to obtain the right List structure.

10.3.1.11. VARIABLE_VALUE_TIME_SERIES Class

Class

VARIABLE_VALUE_TIME_SERIES

Description

Variable value in the form of a time-series.

Inherit

VARIABLE_VALUE

Attributes

Signature

Meaning

0..1

value: Hash<Iso8601_date_time,Any>

Single value, copied or referenced from the Result set of the latest sample of the relevant source Data retrieve frame.

May require transformation to obtain the right Map structure.

10.4. Bindings

The following UML diagram shows the classes and an internal interface relating to bindings.

SM platform.interface.subject proxy binding
Figure 13. Subject Proxy binding

A binding (represented by ENV_BINDING) is understood as a set of retrieval methods (e.g. API invocations, queries) each associated with a single subject variable (represented by VARIABLE_BINDING), for a particular execution environment. A binding may be loaded in the service via the call register_binding ().

10.4.1. Class Definitions

10.4.1.1. I_DATA_BINDING Interface

Interface

I_DATA_BINDING

Description

Internal interface via which Variable bindings are invoked to obtain data.

Attributes

Signature

Meaning

0..1

bindings: List<ENV_BINDING>

Functions

Signature

Meaning

1..1

get_variable (
subject_id: String[1],
name: String[1]
): RESULT_SET_SAMPLE

Execute a retrieve on a single named variable, for a specific subject.

Parameters
subject_id

Identifier of subject against which this request should be made. Note that the identifier might not be the primary identifier for a person or patient, but instead an identifier of an information resource against which the query can be made, e.g. an EHR identifier.

TODO: if a true subject id is passed in, this service might need to resolve it through another service in order to execute the relevant query.

name

Name of the variable.

10.4.1.2. ENV_BINDING Class

Class

ENV_BINDING

Description

Binding for an execution environment to a set of subject variables.

Attributes

Signature

Meaning

0..1

variable_bindings: List<VARIABLE_BINDING>

Bindings for all variables served from this environment.

1..1

env_id: String

Identifier of the environment for which this binding is designed.

10.4.1.3. VARIABLE_BINDING Class

Class

VARIABLE_BINDING

Description

Binding of a named subject variable such as is_type1_diabetic to an extraction method for a particular computing environment.

The variable_name can be used to match subject variables elsewhere in the Subject Proxy stack.

Attributes

Signature

Meaning

0..1

primary_method: SYSTEM_CALL

System call used to perform retrieval of this data frame.

0..1

fallback_method: SYSTEM_CALL

Alternative method to use if primary retrieve method fails.

1..1

variable_name: String

Symbolic name by which this item is known in client applications or services (e.g. CDS, guidelines execution engine).

Typically required to be a legal variable name in a programming language.

1..1

source_type_name: String

Formal name of the expected type of the result of executing either the primary or fallback method. This might not be the same type as expected by the calling system.

1..1

is_manual: Boolean

True if this variable is obtained by manual notification, typically from a worker observing the subject in a point of care situation.

10.5. Usage

The usage of the service follows the general pattern:

  • at system startup, register a binding for an environment, consisting of concrete methods for retrieving and converting data from back-end systems to its variable form;

  • during normal operation, register a subject, typically a patient, but may be any other tracked entity, including devices, sites;

  • add variable definitions to a subject.

The calling sequence to achieve this is of the logical form:

//
// populated in caller
//
sps: I_SUBJECT_PROXY_SERVICE;
var1, var2, var3: SUBJECT_VARIABLE;
env_binding1: ENV_BINDING;

//
// calls to Subject Proxy Service
//
sps.register_binding (env_binding1);

sps.register_subject ("1394850", "individual");
sps.add_subject_variable ("1394850", var1);
sps.add_subject_variable ("1394850", var2);
sps.add_subject_variable ("1394850", var3);

The first call registers a binding for a specific environment. See below for how bindings are defined. The next call creates the subject in the service, while the subsequent add_subject_variable calls are used to build up the proxy variable set for the subject.

This calling sequence suits system initialisation when specific subject proxy variables are created for global use for specific subjects. Typical variables in a healthcare IT environment include date_of_birth and sex.

However many variables are defined by particular applications, including guidelines and planning applications. Accordingly, the service provides a way to register an application data set, i.e. a collection of subject variables, for a subject. In this case, the calling sequence will be of the following form.

//
// populated in caller
//
sps: I_SUBJECT_PROXY_SERVICE;
ds1: SUBJECT_APP_DATA_SET;
env_binding1: ENV_BINDING;

//
// calls to Subject Proxy Service
//
sps.register_binding (env_binding1);

sps.register_subject ("1394850", "individual");
sps.register_application_data_set (ds1);
sps.register_application_data_set (ds1);

In this sequence, the subject variables are established via calls to register_application_data_set, each of which will cause the addition or modification of subject variables not already defined for the subject. When use of an application or subject ceases, the relevant data sets can be removed easily via the various remove_xx calls.

The following example illustrates a typical run-time situation for the use of the Subject Proxy Service.

spo context
Figure 14. Typical Subject Proxy situation

10.6. Specifying a Data-set

A data set specification would be provided through a REST API as a text specification, e.g. in JSON or YAML. Such a specification might be derived from an openEHR Decision Language Modules, or some other source. An example is shown below.

data_set: !!SUBJECT_DATA_SET
    name: antenatal_1.v1.0.3
    creating_app_id: task_planning
    variables:
        - name: date_of_birth
          type_name: Date

        - name: systolic_bp
          type_name: Quantity
          currency: PT2m

        - name: diastolic_bp
          type_name: Quantity
          currency: PT2m

        - name: is_type1_diabetic
          type_name: Boolean

10.6.1. Specifying a Binding

The following shows a partial YAML representation of an ENV_BINDING

binding: !!ENV_BINDING
    variable_bindings:
        - variable_name: date_of_birth
          source_type_name: HL7v3::Date
          primary_method: !!API_CALL
              system_id: pas3.nhs.org.uk
              call_name: cda_admin_request
              parameters:
                  - xxxx: abc
                  - yyyy: def

        - variable_name: systolic_bp
          source_type_name: openEHR::DV_QUANTITY
          primary_method: !!QUERY_CALL
              system_id: ehr1.nhs.org.uk
              call_name: aql_execute
              query_text: xxxx

        - variable_name: is_type1_diabetic
          source_type_name: FHIR::boolean
          primary_method: !!API_CALL
              system_id: ehr1.nhs.org.uk
              call_name: fhir_execute
              query_text: xxxx

11. Terminology Service

11.1. Overview

The platform.interface.terminology package shown below defines service interface to the TERMINOLOGY component in the logical platform architecture. It includes a model for terminology extracts consisting, in general, of terms (either in bare code form or full definition) and relationships.

SM platform.interface.terminology
Figure 15. sm.platform.interface.terminology package

11.2. Class Definitions

11.2.1. I_TERMINOLOGY_SERVICE Interface

Interface

I_TERMINOLOGY_SERVICE

Description

Terminology service interface.

Functions

Signature

Meaning

0..1

get_terminology_ids (): List<String>

Get the identifiers of all terminologies as they are known in this terminology server. These may be URIs. These are the identifiers that may be used in subsequent calls to the service.

1..1

has_terminology (
terminology_id: String[1]
): Boolean

Return True if this server has a terminology with the identifier terminology_id.

1..1

get_terminology_description (
terminology_id: String[1]
): Terminology_description

Pre_has_terminology: has_terminology(terminology_id)

Get the description object for the terminology with identifier terminology_id.

1..1

has_term (
terminology_id: String[1],
code: String[1],
at_date: Iso8601_date[0..1]
): Boolean

Pre_has_terminology: has_terminology(terminology_id)

Return True if the term with code code is known in the terminology with identifier terminology_id. If at_date is specified, the response indicates that the code was present in the terminology at the date.

1..1

get_term (
terminology_id: String[1],
code: String[1],
attributes: Hash<String, String>[0..1],
at_date: Iso8601_date[0..1]
): Terminology_extract

Pre_has_terminology: has_terminology(terminology_id)
Pre_has_term: has_term (terminology_id, code)

Retrieve a term definition from a terminology, including particular attributes i.e. Term_relationships. If at_date is specified, the response is the definition of the term as it was on a certain date.

1..1

subsumes (
terminology_id: String[1],
ref_code: String[1],
candidate_child_code: String[1]
): Boolean

Pre_has_terminology: has_terminology(terminology_id)

Return True if candidate_child_code is in the strict subsumption of ref_code.

1..1

value_set_validate (
terminology_id: String[1],
value_set_id: String[1],
candidate_code: String[1],
at_date: Iso8601_date[0..1]
): Boolean

Pre_has_terminology: has_terminology(terminology_id)

Return True if candidate_code is in the value set identified by value_set_id.

1..1

has_value_set (
terminology_id: String[1],
value_set_code: String[1]
): Boolean

Return True if this terminology service has a value-set identified by value_set_code.

1..1

get_value_set (
terminology_id: String[1],
value_set_code: String[1]
): Terminology_extract

Pre_has_terminology: has_terminology(terminology_id)
Pre_has_value_set: has_value_set (terminology_id, value_set_code)

Retrieve a value-set identified by value_set_code.

11.2.2. Terminology_description Class

Class

Terminology_description

Description

Descriptor for a terminology as it is known in a particular terminology service.

Attributes

Signature

Meaning

1..1

publisher: String

Publisher organisation name.

0..1

available_versions: List<String>

List of identifiers of available versions of this terminology in this service.

0..1

attributes: List<String>

List of meta-model attributes that may be requested within extract requests.

1..1

uri: String

Published and/or standardised identifying URI for the terminology.

11.2.3. Terminology_extract Class

Class

Terminology_extract

Description

Root object of a collection of items extracted from a single version or release of one terminology. The sub-parts all assume the same terminology meta-data carried in the root object.

May be used to represent any extract, including:

  • a 'flat' value-set (i.e. no relationships);

  • a structured value-set (aka 'ref set');

  • a subsumption hierarchy below a specified concept.

Attributes

Signature

Meaning

1..1

terminology_id: String

The archetype environment namespace identifier used to identify a terminology. Typically a value like "snomed_ct" that is mapped elsewhere to the full URI identifying the terminology.

0..1

terminology_version: String

Optional string value representing terminology version, typically a date or dotted numeric.

0..1

terms: Hash<String,Term_code>

Set of terms in extract, each of which may be a bare code, or have displayable text included, via the Term subtype.

0..1

relationships: List<Term_relationship>

List of relationships according to specification generating extract.

0..1

relations: Hash<String,Terminology_relation>

Definitions of relations used in this extract, keyed by name.

Functions

Signature

Meaning

1..1

create_terminology_code (
code: String[1]
): Terminology_code

Generate the standalone form of a Terminology code.

11.2.4. Terminology_relation Class

Class

Terminology_relation

Description

Definition of a relationship within the terminology meta-model. May have a terminology code (local_code) from the terminology of this extract, or be defined by a code from another terminology that includes the meta-model of this terminology (external_code).

Attributes

Signature

Meaning

1..1

name: String

Name of this relation from relevant meta-model.

0..1

local_code: String

Local code defining this relation, if in a terminology whose meta-model is defined as terms.

0..1

external_code: Terminology_code

Code from another terminology that defines a relation used by this terminology. Used for terminologies that don’t have codes for their own meta-model.

Invariants

Inv_valid_definition: local_code /= Void xor external_code /= Void

11.2.5. Term_relationship Class

Class

Term_relationship

Description

Term relationship, represented as a 1:N code map in the scope of the terminology identified by the owning extract.

Attributes

Signature

Meaning

1..1

origin_code: String

Code of origin (i.e 'left-hand') concept in this relation.

1..1

relation_name: String

Name of the relation; must match a key in the owning Terminology_extract.relations.

0..1

target_codes: List<String>

Codes of target (i.e 'right-hand') concept(s) in this relation.

11.2.6. Term_code Class

Class

Term_code

Description

Pure terminology concept within the scope of the terminology of the owning extract.

Attributes

Signature

Meaning

1..1

code: String

A terminology code or post-coordinated code expression, if supported by the terminology. The code may refer to a single term, a value set consisting of multiple terms, or some other entity representable within the terminology.

11.2.7. Defined_term Class

Class

Defined_term

Description

Fully defined term within the scope of the terminology of the owning extract.

Inherit

Term_code

Attributes

Signature

Meaning

1..1

text: String

Text of term.

0..1

language: Terminology_code

Optional code representing the language. Strongly recommended to be an ISO 639 2- or 3- character code, or an IETF RFC 5646 language-region tag (e.g. 'en-GB').

0..1

is_preferred_term: Boolean

True if this term is the preferred term among alternatives, if supported within the scoping terminology.

12. Admin Service

12.1. Overview

The platform.interface.admin package shown below defines service interface to the ADMIN component in the logical platform architecture.

SM platform.interface.admin
Figure 16. sm.platform.interface.admin package

12.2. Class Definitions

12.2.1. I_ADMIN_SERVICE Interface

Interface

I_ADMIN_SERVICE

Description

Primary ADMIN_SERVICE Interface.

Functions

Signature

Meaning

0..1

list_contributions (
a_service: PLATFORM_SERVICE[1],
time_interval: Interval<Iso8601_date_time>[0..1]
): List<UUID>

Obtain a list of ids of all Contributions in EHR system; an optional time range may be supplied.

Parameters
a_service

Name of a versioned content service (enumeration value).

1..1

contribution_count (
a_service: PLATFORM_SERVICE[1],
time_interval: Interval<Iso8601_date_time>[0..1]
): Integer

Obtain the count of all Contributions made on EHR system; an optional time range may be supplied.

1..1

versioned_composition_count (
a_service: PLATFORM_SERVICE[1],
time_interval: Interval<Iso8601_date_time>[0..1]
): Integer

Obtain the count of all Versioned Compositions on EHR system; an optional time range may be supplied.

1..1

composition_version_count (
a_service: PLATFORM_SERVICE[1],
time_interval: Interval<Iso8601_date_time>[0..1]
): Integer

Obtain the count of all Composition Versions on EHR system; an optional time range may be supplied.

0..1

physical_ehr_delete (
an_ehr_id: UUID[1]
)

Pre_has_ehr: has_ehr (an_ehr_id)

Physical deletion of specified EHR.

Errors
  • ehr_id_does_not_exist

0..1

physical_party_delete (
a_party_id: UUID[1]
)

Physical delete of specified Party, along with related Party relationships.

Errors
  • party_id_does_not_exist

12.2.2. I_ADMIN_ARCHIVE Interface

Interface

I_ADMIN_ARCHIVE

Description

Interface for Archive-related functions.

Functions

Signature

Meaning

0..1

archive_ehrs (
ehr_ids: List<UUID>[0..1]
)

Move selected EHRs to archival storage.

Errors
  • ehr_id_does_not_exist

0..1

archive_parties (
party_ids: List<UUID>[0..1]
)

Move selected Parties and relationships to archival storage.

Errors
  • party_id_does_not_exist

12.2.3. I_ADMIN_DUMP_LOAD Interface

Interface

I_ADMIN_DUMP_LOAD

Description

Interface to dump/load facilities.

Functions

Signature

Meaning

0..1

export_ehrs (
file_sys_loc: String[1],
logical_fmt: EXPORT_FORMAT[0..1],
comp_fmt: COMPRESSION_FORMAT[0..1],
enc_format: ENCODING_FORMAT[0..1]
)

Export all EHRs to a file-system location in a specified format.

Parameters
file_sys_loc

File system location to write archive to.

Errors
  • file_not_writable

0..1

load_ehrs (
file_sys_loc: String[1]
)

Populate EHR repository from export archive on file system. Repository need not be empty, but import EHRs with duplicate EHR ids will fail.

Errors
  • file_not_writable

12.2.4. DUMP_LOAD_FAIL_REPORT Class

Class

DUMP_LOAD_FAIL_REPORT

Description

Dump or Load fail report for a single entity, e.g. EHR, PARTY etc .

Attributes

Signature

Meaning

1..1

entity_type: String

Type name of entity.

1..1

entity_id: String

Identifier of entity.

1..1

dump_status: Boolean

Status of entity in dump operation: True means successfully dumped; False means dump failed for this entity.

0..1

error: String

Detailed error information, if available.

12.2.5. EXPORT_SPEC Class

Class

EXPORT_SPEC

Description

Specifies the details for an export operation.

Attributes

Signature

Meaning

0..1

logical_format: EXPORT_FORMAT

Logical format to use, i.e. flavour of XML, JSON etc.

0..1

compression_format: COMPRESSION_FORMAT

Compression format to use during dump.

0..1

encoding: ENCODING_FORMAT

Encoding to use.

1..1

segment_split_size: Integer

Size in kb of segment size on file system to split export into.