openEHR logo

openEHR Platform Service Model

Issuer: openEHR Specification Program

Release: SM development

Status: TRIAL

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: openehr, service, API

openEHR components
© 2017 - 2024 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

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 Gutierrez, CaboLabs, 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/development/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.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.common
Figure 4. sm.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.

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.3.1. Query Formalism

A stored or ad hoc query text has an associated formalism, i.e. query language, provided in the a_type parameter in various calls. This parameter is a string value, treated case-insensitively carrying the name of the formalism of the query text, with an optional version identifier separated by the '::' delimiter. The version identifier may be:

  • a semver.org partial or full version string, such as "1", "1.0", "1.0.3"; OR

  • any text value, for non-computable version identifiers.

If no version identifier part is supplied, the major version "1" is assumed.

Accordingly, the following values for the type parameter are all equivalent:

  • "AQL"

  • "aql"

  • "AQL::1"

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_type: String[1]
): Boolean

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

Parameters
a_type

Name and optionally version of the query formalism (i.e. language).

1..1

store_query (
a_query_text: String[1],
a_type: 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_type

Name and optionally version of the query formalism (i.e. language).

1..1

store_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.

5.2.8. UV_FOLDER Class

Class

UV_FOLDER

Description

Form of UPDATE_VERSION specific to FOLDER.

Inherit

UPDATE_VERSION

5.2.9. UV_COMPOSITION Class

Class

UV_COMPOSITION

Description

Form of UPDATE_VERSION specific to COMPOSITION.

Inherit

UPDATE_VERSION

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

6.2.4. UV_PARTY Class

Class

UV_PARTY

Description

Form of UPDATE_VERSION specific to PARTY.

Inherit

UPDATE_VERSION

6.2.5. UV_PARTY_RELATIONSHIP Class

Class

UV_PARTY_RELATIONSHIP

Description

Form of UPDATE_VERSION specific to PARTY_RELATIONSHIP.

Inherit

UPDATE_VERSION

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 (SPS)

10.1. Overview

The Subject Proxy Service (SPS) allows symbolic variables characterising the real world state of a subject which is often a subject of care (i.e a patient) but may be some other entity, to be retrieved and tracked over time. Such variables are useful for many kinds of application, since they provide a standard means of obtaining information that concretely reside in different kinds of back-end systems or devices, or may be requested from live users. The SPS avoids the calling application having to know about the particular standard, representational model, query language or API of the data source for any given variable. Consequently there is no need to even assume that an openEHR back-end system is the source of any given variable.

The following diagram shows conceptually the population of subject proxy variables from back-end systems, via the various intermediate layers of the Subject Proxy Service.

spo conceptual
Figure 11. Typical Subject Proxy situation

Subject variables may be conveniently used by any application and are relied upon by openEHR Task Plans and Decision Logic Modules, for which the conceptual purpose and typical use are described in the openEHR Process and Planning Overview.

10.2. Subject Variable Naming

The Subject Proxy Service enables the registration of subject variables by various means. Each subject variable is identified within the service by a canonical name (SUBJECT_VARIABLE.canonical_name, in the model below), which is the name used for it in calls mentioning variables by name.

The canonical name is formed from SUBJECT_VARIABLE.name, prefixed by namespace if it is set, and are unique within the service, regardless of which subjects or applications may use them at any given time. The name attribute is an intelligible natural language names that accurately indicate its meaning, such as "date_of_birth", "is_type1_diabetic" and so on, but may be any name that is legal within the relevant source contexts and valid within this service. Some variable names such as "date_of_birth" are regarded as having a globally agreed definition (e.g. the date recorded as date of birth against the subject in administration systems), while other variables such as has_heart_failure may have a definitions specific to particular guidelines, such as CHA2DS2-VASc, a guideline for atrial fibrillation (AF) diagnosis etc. The use of namespaces in the latter cases would have the effect of defining variables such as cha2ds2vasc::has_heart_failure and af_diagnosis::has_heart_failure (where "cha2ds2vasc" and "af_diagnosis" are namespace values), each of which may have a semantically different retrieval definition (for example including or excluding heart murmur).

If namespace is not set, the variable is understood to be in the 'global' namespace, and to have the same meaning for all users. There is nothing to stop a variable existing in both the global namespace and one or more specific namespaces, for example date_of_birth (standard administrative concept) and tribal::date_of_birth (a specific 'date of birth' concept used for ethnic or religious reasons).

To be valid within the service, canonical names may not contain whitespace or any unprintable character, but there are no other restrictions (e.g. of case, or first character being a letter etc).

An application data set, which is a convenience collection of variables registered by / for an application may however use data set-local aliases, for example "dob" for the canonical name "date_of_birth". This allows the names used locally within client computation contexts for the same variable registered in the SPS may differ. It is recommended that this flexibility be used sparingly in order to limit confusion within the overall system design environment.

10.3. Service Interface

The SPS supports the following abstract kinds of operations (with variants):

  • Register a subject: create a new subject in the service, with which which variables can be associated;

  • Add subject variable: add a subject variable definition to an existing subject;

  • Register application data set: register a set of subject variables for a particular application;

  • Register binding: add a binding for an 'environment', which is usually a concrete computing context containing multiple back-end systems from which subject variables can be populated;

  • Add binding data frame: add a data retrieval frame to an environment binding - this provides a data access method for that environment.

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.

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

10.4. Data Structures

The data entities used by the SPS are conceptually as follows:

  • Subject proxy: a container for all variables and data sets for a single subject;

  • Subject variable: a proxy for a single subject variable, including sample history over time;

  • Subject data set: a proxy for a particular set of variables in use by some application;

  • Sample: a sample represents a time-stamped result of a request to obtain a value via its binding, and either contains a value, or an 'unavailable' flag and reason;

  • Variable value: a variable value is the value of some variable as it was at a moment in time, and may take various forms.

The formal class definitions are shown in the following UML.

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

10.5. Samples

The SAMPLE class provides a generic wrapper for any retrieved back-end data, stamping it with a retrieve_time and a is_unavailable flag in case no data could be obtained. The optional effective_time represents the clinically relevant time of the sample, which is comparable to currency in order to determine the freshness of the data. The descendant DATA_FRAME_SAMPLE specialises the payload to full data frame results, which may be large query results, complex data objects etc, or indeed, single values.

The following UML shows the Sample hierarchy.

SM platform.interface.subject proxy sample
Figure 14. Subject Proxy structures

10.6. Bindings

A binding (represented by ENV_BINDING) is understood as a set of retrieval methods (e.g. API invocations, queries) each defined by a data frame (represented by DATA_FRAME), for a particular execution environment, and independent of any particular subject. A binding may be loaded in the service via the call register_binding(). Each data frame has a primary and optionally a fallback method which can be executed to obtain the data, as well as a retrieval result, in the native format of the API used to access the source system, e.g. openEHR AQL Result_set, a particular FHIR profiled resource, an HL7v2 message, XDS document and so on. The interface I_DATA_BINDING provides a (partially specified) internal API for retrieving a result from a particular data frame.

The retrieved data frame results are of type DATA_FRAME_SAMPLE, representing a single 'sample' of some kind of retrieval result from a back-end system or interoperability gateway. The descendant types provide a few common forms.

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

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

10.7. Persistence

It is assumed that the configuration contents (i.e. not data frame or variable results) of the SPS are persisted for the life of the system i.e. until the point of any system level re-initialisation actions. The SPS includes a reset() operation that enables all content to be dumped, returning the service to its virgin state.

10.8. 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, ds2: 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 (ds2);

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 16. Typical Subject Proxy situation

10.8.1. 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.8.2. Specifying a Binding

The following shows a partial YAML representation of an ENV_BINDING for a particular deployment environment.

binding: !!ENV_BINDING
    data_frames:
        - frame_id: OracleMPI::basic_demographics
          model_type: OracleMPI
          primary_method: !!API_CALL
              system_id: pas3.nhs.org.uk
              call_name: REST_get
              parameters:
                  - xxxx: abc
                  - yyyy: def

        - frame_id: openEHR::vital_signs
          model_type: openEHR-EHR
          primary_method: !!QUERY_CALL
              system_id: ehr1.nhs.org.uk
              call_name: aql_query
              query_text: xxxx

        - frame_id: OracleMPI::basic_demographics
          model_type: HL7-FHIR_DSTU4_UK
          primary_method: !!API_CALL
              system_id: ehr1.nhs.org.uk
              call_name: fhir_get
              query_text: xxxx

10.9. Class Descriptions

10.9.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_application_data_set (
definition: SUBJECT_DATA_SET[1]
)

Pre_subject_valid: has_subject(subject_id)

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.

0..1

get_variable_defs (
subject_id: String[1]
): List<String>

Return a list of variable definitions each of the form "name: Type", where 'name' is the canonical name, i.e. SUBJECT_VARIABLE.name.

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.

TODO: determine whether SPS is 1:1 with an 'environment', in which case, only one binding is ever required in a system instance.

0..1

add_binding_frame (
env_id: String[1],
frame[1]
)

Pre_valid_binding: has_binding(env_id)

Add a retrieve frame definition to the binding container for an environment.

1..1

has_binding (
env_id: String[1]
): Boolean

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

0..1

reset

Set back to virgin state, i.e. remove all subjects, variables and bindings.

10.9.2. 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: Hash<String,SUBJECT_DATA_SET>

All data sets for this subject.

10.9.3. SUBJECT_VARIABLE Class

Class

SUBJECT_VARIABLE

Description

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

Variables are considered either global, having just a name, or qualified, in which case namespace is also set. A name-spaced variable is one whose meaning is relative to the context of the name-space, typically a specific guideline.

Attributes

Signature

Meaning

0..1

namespace: String

Optional namespace qualifying name. Used to distinguish variables that may have the same name but have local meanings within specific contexts, e.g. specific guidelines.

For example, a variable has_heart_failure is likely to have definitions specific to particular guidelines, such as CHA2DS2-VASc and (say) a guideline for CHF diagnosis. The use of namespaces in both cases would have the effect of defining variables such as cha2ds2vasc::_has_heart_failure_ and chf_diagnosis::_has_heart_failure_, each of which may have a different retrieval definition.

If not set, the variable is understood to be in a 'global' namespace, and to have the same meaning for all users, as is likely to be the case for a variable such as is_type1_diabetic.

1..1

name: String

Canonical name by which this item is known in the service. 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.

0..1

history: List<VARIABLE_SAMPLE>

Samples constituting the retrieve history of this variable.

1..1

frame_id: String

Identifier of retrieve frame from which to extract this variable.

0..1

last_frame: DATA_FRAME_SAMPLE

Most recent retrieve frame from which to extract variable value.

1..1

frame_path: String

Path within last_frame result.

Functions

Signature

Meaning

1..1

canonical_name (): String

Return canonical name, formed from namespace (if present) and name. In the first case, the result will be namespace::name, in the latter, just name.

1..1

value (): VARIABLE_SAMPLE

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

1..1

is_global (): Boolean

Post_result: Result = (namespace = Void)

True if namespace is set.

10.9.4. 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

id: String

Unique identifier of this data set with respect to other data sets in use for the same subject. Usually derived from some application semantic label, such as a guideline id or similar.

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 keyed by local name within the data set, which may differ from the SUBJECT_VARIABLE.name, which is the canonical name in the service. For example, a variable whose canonical name is "date_of_birth" may be known within a data set as "dob".

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.9.5. 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.9.6. SAMPLE Class

Class

SAMPLE<T> (abstract)

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.9.7. DATA_FRAME_SAMPLE Class

Class

DATA_FRAME_SAMPLE<T> (abstract)

Description

Abstract class with methods for extracting single variable values from data frames.

Inherit

SAMPLE

10.9.8. OPENEHR_SAMPLE Class

Class

OPENEHR_SAMPLE

Description

openEHR sample whose result is in the form of a RESULT_SET structure.

Inherit

DATA_FRAME_SAMPLE

Attributes

Signature

Meaning

0..1
(redefined)

result: RESULT_SET

Result of retrieve call execution.

10.9.9. HL7v2_SAMPLE Class

Class

HL7v2_SAMPLE

Description

Container for HL7v2 message based data frame results.

Inherit

DATA_FRAME_SAMPLE

10.9.10. HL7_FHIR_SAMPLE Class

Class

HL7_FHIR_SAMPLE

Description

Container for HL7 FHIR based data frame results.

Inherit

DATA_FRAME_SAMPLE

10.9.11. 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.9.12. VARIABLE_VALUE Class

Class

VARIABLE_VALUE (abstract)

Description

Abstract parent of variable value structures.

Inherit

Any

10.9.13. 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.9.14. 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.9.15. 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.9.16. 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>

All bindings registered in this service, one per environment.

Functions

Signature

Meaning

1..1

get_frame (
subject_id: String[1],
frame_id: String[1]
): DATA_FRAME_SAMPLE

Execute a retrieve on a data frame, 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.

frame_id

Name of the variable.

10.9.17. ENV_BINDING Class

Class

ENV_BINDING

Description

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

Attributes

Signature

Meaning

1..1

env_id: String

Identifier of the environment for which this binding is designed.

0..1

description: String

An informal description of the environment useful for display and other human consumption.

0..1

data_frames: List<DATA_FRAME>

10.9.18. DATA_FRAME Class

Class

DATA_FRAME

Description

Data retrieval frame, consisting of primary and fallback retrieval methods (i.e. calls, or parameters for standard calls), and most recent result.

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

id: String

1..1

model_type: String

Name of underlying model / type system, e.g. "openehr", "hl7v2", "hl7-fhir" etc. Currently not standardised.

Functions

Signature

Meaning

1..1

execute (): DATA_FRAME_SAMPLE

Partially specified execute method to obtain a Result set

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 17. 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 18. 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.

13. Amendment Record

Issue Details Raiser Completed

SM Release 1.0.0 (unreleased)

0.9.8

Fixes to specific interfaces due to SEC analysis:
Rename I_DEFINITION_QUERY.register_xx to store_xx and formalism parameter to a_type; document representation of formalism version;

S Iancu

13 Dec 2021

0.9.7

Add Subject Proxy Service.

T Beale

01 Apr 2021

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