openEHR logo

openEHR Platform Abstract Service Model

Issuer: openEHR Specification Program

Release: latest

Status: TRIAL

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: openehr, service, API

openEHR components
© 2017 - 2018 The openEHR Foundation

The openEHR Foundation is an independent, non-profit community organisation, facilitating the sharing of health records by consumers and clinicians via open-source, standards-based implementations.

Licence

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

Support

Issues: https://openehr.atlassian.net/browse/SPECPR/
Web: www.openehr.org

Amendment Record

Issue Details Raiser Completed

R E L E A S E     1.0.0

0.9.4

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

T Beale

17 Mar 2018

0.9.3

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

T Beale

14 Feb 2018

0.9.2

Improve documentation text;
remove auth_tok argument from calls.

T Beale

22 Oct 2017

0.9.1

Added demographic interface calls;
added more admin interface calls.

T Beale

18 Oct 2017

0.9.0

SPECSM-1: Initial writing.

openEHR SEC

15 Sep 2017

Acknowledgements

Contributors

This specification has benefited from formal and informal input from the openEHR community.

Trademarks

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

1. Preface

1.1. Purpose

This document specifies core components of the openEHR platform 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 www.openehr.org/releases/SM/latest/openehr_platform.html.

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

TBD: (example To Be Determined paragraph)

Users are encouraged to comment on and/or advise on these paragraphs as well as the main content. Feedback should be provided either on the technical mailing list, or on the specifications issue tracker.

2. Overview

2.1. openEHR Platform Model

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, RPC, Protocol Buffers, on so on, each of which has its own characteristics and rules.

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

SM platform definition
Figure 1. sm.openehr_platform.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

Admin

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

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.

2.2. 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.3. 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.4. Global Conventions

2.4.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.4.2. List-handling

Calls that result in 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:

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

2.4.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 ISO8601 format (e.g. 2015-01-20T19:30:22.765+01:00)

2.5. Package Structure

The openEHR Platform Service Model package structure is illustrated below. It consists of two outer packages, platform_definition and platform_interface. The former contains the service components, while the latter contains the interfaces attached to each service component.

SM platform packages
Figure 2. sm.openehr_platform Package Overview

3. Common Package

3.1. Overview

The platform_interface.common package shown below defines common elements of the platform service model. The key elements are:

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

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

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

SM platform interface.common
Figure 3. sm.openehr_platform.platform_interface.common package

3.2. Class Definitions

3.2.1. I_STATUS Interface

Interface

I_STATUS

Description

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

Functions

Signature

Meaning

last_call_failed (): Boolean

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

last_call_status (): CALL_STATUS

Class status object for last call.

3.2.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.2.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.2.4. UPDATE_VERSION Class

Class

UPDATE_VERSION (abstract)

Description

An object representing an update to an existing VERSION, that can be provided by a client to the platform. The back-end will construct a full VERSION object from this and server-side generated data items.

Attributes

Signature

Meaning

0..1

preceding_version_uid: OBJECT_VERSION_ID

Stored version of inheritance precursor.

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.2.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)

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 4. sm.openehr_platform.platform_interface.definitions package

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

4.2. Archetypes and Templates

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

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

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

4.3. Registered Queries

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

  • <namespace>::<query-name>

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

Examples:

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

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

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

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

4.4. Class Definitions

4.4.1. I_DEFINITION_ADL2 Interface

Interface

I_DEFINITION_ADL2

Description

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

Functions

Signature

Meaning

has_artefact (
an_id: ARCHETYPE_HRID[1]
): Boolean

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

upload_artefact (
an_arch: AUTHORED_ARCHETYPE[1]
)
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)

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

list_all_artefacts (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

List all AOM2 artefacts known in the service.

list_all_archetypes (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

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

list_all_templates (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

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

list_all_opts (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<ARCHETYPE_HRID>

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

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

List all artefacts whose identifiers match a regex pattern.

Errors
  • invalid_id_pattern

delete_artefact (
an_id: ARCHETYPE_HRID[1]
)

Delete the AOM2 artefact with id an_id.

Errors
  • artefact_does_not_exist

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

has_archetype (
an_id: ARCHETYPE_ID[1]
): Boolean

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

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

get_archetype (
an_id: ARCHETYPE_ID[1]
): ARCHETYPE

Get the ADL 1.4 archetype with id an_id.

Errors
  • artefact_does_not_exist

list_all_archetypes (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<ARCHETYPE_ID>

List all ADL 1.4 archetypes known in the service.

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

List all archetypes whose identifiers match a regex pattern.

Errors
  • invalid_id_pattern

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

has_opt (
an_id: UUID[1]
): Boolean

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

upload_opt (
arch: ARCHETYPE[1]
)

Upload an ADL 1.4 Operational Template (OPT).

Errors:
  • invalid_template

get_opt (
an_id: UUID[1]
): ARCHETYPE

Get the ADL 1.4 OPT with id an_id.

Errors
  • artefact_does_not_exist

list_all_opts (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<UUID>

List all AD 1.4 OPTs known in the service.

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

List all OPTs whose identifiers match a regex pattern.

Errors
  • invalid_id_pattern

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

4.4.3. I_DEFINITION_QUERY Interface

Interface

I_DEFINITION_QUERY

Description

Interface for storying queries and query sets.

Functions

Signature

Meaning

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.

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

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

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

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

Parameters
a_formalism

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

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

Register a query set.

TODO: determine details.

list_all_queries (
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<QUERY_DESCRIPTOR>

List all registered queries.

list_matching_queries (
id_pattern: String[1],
artefact_id_pattern: String[1],
row_offset: Integer[0..1],
rows_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

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

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_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

query_id: UUID

Unique query identifier associated with this query.

TBD: needed, or just rely on qualified names?

0..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".

1..1

registration_time: Iso8601_date_time

Time query was registered in the service.

5. EHR Package

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 5. sm.openehr_platform.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

has_ehr (
ehr_id: UUID[1]
): Boolean

Return True if a EHR with identifier ehr_id exists.

Parameters
ehr_id

EHR identifier.

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

create_ehr (
an_ehr_status: EHR_STATUS[0..1]
): UUID
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.

create_ehr_with_id (
an_ehr_id: UUID[1],
an_ehr_status: EHR_STATUS[0..1]
): UUID
Post_has_ehr: has_ehr (Result)
Pre_no_duplicate: not has_ehr (an_ehr_id)

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

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

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

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

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

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.

Functions

Signature

Meaning

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

Obtain a list of identifiers of Contributions in EHR.

Parameters
ehr_id

EHR identifier (UUID).

time_range

Optional time range to limit Contributions to.

Errors
  • ehr_does_not_exist

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.3. I_EHR_STATUS Interface

Interface

I_EHR_STATUS

Description

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

Functions

Signature

Meaning

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

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

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

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

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

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

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

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

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

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

has_directory (
ehr_id: UUID[1]
): Boolean
Pre_has_ehr: has_ehr (an_ehr_id)

True if the EHR has a directory structure.

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

create_directory (
ehr_id: UUID[1],
a_dir_struct: UV_FOLDER[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)
Pre_no_directory: not has_directory (ehr_id)

Create a directory in the EHR, based on the provided structure.

Errors
  • ehr_id_does_not_exist

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

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

update_directory (
ehr_id: UUID[1],
a_dir_struct: UV_FOLDER[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)
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.

Parameters
a_dir_struct

Directory structure with which to replace current structure.

Errors
  • ehr_id_does_not_exist

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

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

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

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

has_composition (
an_ehr_id: UUID[1],
a_version_uid: UUID[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

get_composition (
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

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

create_composition (
an_ehr_id: UUID[1],
a_comp: UV_COMPOSITION[1]
): UUID
Pre_has_ehr: has_ehr (an_ehr_id)
Post_has_composition: has_composition (an_ehr_id, Result)

Create the first version of a new Composition.

Errors
  • ehr_id_does_not_exist

  • composition_already_exists

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

Update an existing Composition with a new version.

Errors
  • ehr_id_does_not_exist

  • composition_does_not_exist

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

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

Get a particular VERSION of a Composition by version id.

Parameters
a_version_uid

Uid of a VERSION in a VERSIONED_COMPOSITION.

Errors
  • ehr_does_not_exist

  • object_version_does_not_exist

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

5.2.6. I_EHR_CONTRIBUTION Interface

Interface

I_EHR_CONTRIBUTION

Description

Interface for explicit Contribution level operations.

Functions

Signature

Meaning

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

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

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 VERSION_UPDATE objects.

Errors
  • ehr_id_does_not_exist

list_all_contributions (
an_ehr_id: UUID[1],
row_offset: Integer[0..1],
rows_to_fetch: Integer[0..1]
): List<UUID>

List all available Contributions for this EHR.

Errors
  • ehr_id_does_not_exist

5.2.7. EHR_SUMMARY Class

Class

EHR_SUMMARY

Description

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

Attributes

Signature

Meaning

1..1

ehr_id: UUID

EHR identifier of this EHR.

1..1

system_id: String

Copy of EHR.system_id.

1..1

ehr_status: EHR_STATUS

Copy of EHR.ehr_status.

1..1

time_created: Iso8601_date_time

Copy of EHR.time_created.

1..1

contribution_count: Integer

Number of Contributions in this EHR.

1..1

composition_count: Integer

Number of (versioned) Compositions in this EHR.

6. Demographic Package

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 6. sm.openehr_platform.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

create_party (
a_version: UV_PARTY[1]
): UUID

Create a new Party.

create_party_relationship (
a_version: UV_PARTY_RELATIONSHIP[1]
): UUID

Create a new Party Relationship.

i_party (
a_versioned_party_id
): I_PARTY

Create an I_PARTY interface.

Errors
  • versioned_object_does_not_exist

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

has_party (
a_versioned_party_id: UUID[1]
): Boolean

Return True if Party exists.

has_party_version_id (
a_party_version_id: UUID[1]
): Boolean

True if a particular version of a Party exists.

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

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

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

Update a Party with a new Version.

Errors
  • versioned_object_does_not_exist

  • object_version_does_not_exist

delete_party (
a_versioned_party_id: UUID[1]
)
Post_party_deleted: not has_party (a_versioned_party_id)
Pre_has_party: has_party (a_versioned_party_id)

Delete an existing Party.

Errors
  • versioned_object_does_not_exist

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

has_party_relationship (
a_versioned_party_rel_id: UUID[1]
): Boolean

Return True if Party relationship exists in service.

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

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

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

Update a Party relationship with a new Version.

Errors
  • versioned_object_does_not_exist

  • object_version_does_not_exist

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

get_party_relationship_at_version (
a_party_rel_version_id: UUID[1]
): PARTY_RELATIONSHIP

Get a particular Party relationship Version.

Errors
  • object_version_does_not_exist

7. EHR Index Package

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 7. sm.openehr_platform.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

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.

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

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

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

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 Package

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 8. sm.openehr_platform.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 row_offset and rows_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

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

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.

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.

0..1

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

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

query_text: String

AQL text of query.

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.

Attributes

Signature

Meaning

0..1

query_name: String

Name of query if stored in Definitions service.s

1..1

source_aql_text: String

Source AQL text to be executed, once paramaters are substituted.

0..1

rows: List<RESULT_SET_ROW>

Result row data.

1..1

columns: List<RESULT_SET_COLUMN>

Column definition structure.

0..1

executed_aql: String

Executed AQL text with all parameters substituted.

1..1

creation_time: Iso8601_date_time

Time of creation of this Result set by execution engine.

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.

1..1

aql_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

items: List<Any>

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

9. Message Package

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 9. sm.openehr_platform.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

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

Export whole EHR for one or more subjects.

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

Export an extract for one or more EHRs.

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.

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

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

Import a TDD.

import_tdds

Bulk import numerous TDDs.

10. Admin Package

10.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 10. sm.openehr_platform.platform_interface.admin package

10.2. Class Definitions

10.2.1. I_ADMIN_SERVICE Interface

Interface

I_ADMIN_SERVICE

Description

Primary ADMIN_SERVICE Interface.

Functions

Signature

Meaning

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

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.

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.

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.

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

physical_party_delete (
a_party_id: UUID[1]
)

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

Errors
  • party_id_does_not_exist

10.2.2. I_ADMIN_ARCHIVE Interface

Interface

I_ADMIN_ARCHIVE

Description

Interface for Archive-related functions.

Functions

Signature

Meaning

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

Move selected EHRs to archival storage.

Errors
  • ehr_id_does_not_exist

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

Move selected Parties and relationships to archival storage.

Errors
  • party_id_does_not_exist

10.2.3. I_ADMIN_DUMP_LOAD Interface

Interface

I_ADMIN_DUMP_LOAD

Description

Interface to dump/load facilities.

Functions

Signature

Meaning

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

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

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

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