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 - 2017 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.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 interface call semantics independent of any particular 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, etc, each of which has its own characteristics and rules.

The following figure illustrates the assumed components of an abstract openEHR Platform.

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 an abstract transactional interface to the service provided by the component. Each interface consists of a number of calls, and each call is defined in an abstract way.

This view does not attempt to define or specify any real product architecture as produced by a platform developer, but instead, to standardise the naming of components and semantics of their logical interfaces so that platform procurers and users can speak of, for example, the 'Admin service' or the 'EHR service' within tender documents, without ambiguity. The abstract service architecture described here provides platform implementers a standard reference point for mapping agreed functionality (such as requested in a tender or other solicitation) into their own architectures, which may be organised quite differently.

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 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 bothl 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 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 semantics described here prior and after the call(s) are the same in both cases. If this is not true, it implies that the implementation is doing something different than what is specified.

2.3. Anatomy of an Abstract Call Specification

A fuller specification of any function or procedure includes its semantic effects, stated in terms of pre-conditions, post-conditions and exception cases, along with documentation. 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 pro- 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

a_uuid: UUID

A UUID.

Pre-conditions

Valid_id: not has_ehr (an_id)

Post-conditions

Ehr_created: has_ehr (an_id)

Exceptions

Ehr_already_exists

EHR with <an_id> already exists.

Auth_error

Caller not authorised to make this call.

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

2.4. Functional Style

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

  • stateless / mostly stateless / stateless;

  • use of pre- and post-conditions and exception-handling style;

  • 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 notional call sequence for any given call 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 notional 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 helping to explain the semantics within context of the interface calls documented in this specification.

2.5. Package Structure

The openEHR Platform Service Model package structure is illustrated below.

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 srevice model.

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_STATUSES

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_STATUSES Enumeration

Enumeration

CALL_STATUSES

Description

Enumeration representing standard call statuses.

Attributes

Signature

Meaning

success

Call succeeded.

auth_failure

Authorisation failure.

precondition_violation

Precondition violation occurred.

exception

Exception other than precondition violation occurred.

3.2.4. UPDATE_VERSION Class

Class

UPDATE_VERSION

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.definition package shown below defines service interface to the definitions component in the logical platform architecture.

SM platform interface.definition
Figure 4. sm.openehr_platform.platform_interface.definition 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. Class Definitions

4.2.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 (
arch: AUTHORED_ARCHETYPE[1]
)

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.

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.

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

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.

delete_artefact (
an_id: ARCHETYPE_HRID[1]
)

Delete the AOM2 artefact with id an_id.

Errors
  • artefact_does_not_exist

4.2.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 (
arch: ARCHETYPE[1]
)

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.

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

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

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

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.

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

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

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

4.2.3. I_DEFINITION_QUERY Interface

Interface

I_DEFINITION_QUERY

Description

Interface for storying queries and query sets.

Functions

Signature

Meaning

has_query (
a_query_id: UUID[1]
): Boolean

Return True if the query identified by a_query_id is registered.

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

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

TODO: validate query text?

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.

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

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

Errors
  • invalid_id_pattern

Parameters
id_pattern

PERL regular expression on query identifier.

artefact_id_pattern

PERL regular expression on archetype / template identifiers.

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

delete_query (
a_query_id: UUID[1]
)

4.2.4. DEFINITION_CALL_STATUSES Enumeration

Enumeration

DEFINITION_CALL_STATUSES

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

TODO: only by this service?

0..1

query_name: String

Unique name of query.

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.

Errors
  • ehr_does_not_exist

Parameters
a_subject_id

Subject identifier.

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

Errors
  • ehr_does_not_exist

Parameters
an_ehr_id

EHR identifier (a UUID).

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.

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.

Errors
  • ehr_does_not_exist

Parameters
an_ehr_id

EHR identifier (a UUID).

a_subject_id

Subject identifier.

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.

Errors
  • ehr_does_not_exist

Parameters
an_ehr_id

EHR identifier (a UUID).

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.

i_ehr (): I_EHR

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

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.

Errors
  • ehr_does_not_exist

Parameters
ehr_id

EHR identifier (UUID).

time_range

Optional time range to limit Contributions to.

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

Obtain a count of Contributions in EHR.

Errors
  • ehr_does_not_exist

Parameters
ehr_id

EHR identifier (Guid).

time_range

Optional time range to limit Contributions count to.

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

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_does_not_exist

set_ehr_queryable (
an_ehr_id: UUID[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)

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

Errors
  • ehr_does_not_exist

set_ehr_modifiable (
an_ehr_id: UUID[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)

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

Errors
  • ehr_does_not_exist

clear_ehr_queryable (
an_ehr_id: UUID[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)

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

Errors
  • ehr_does_not_exist

clear_ehr_modifiable (
an_ehr_id: UUID[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)

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

Errors
  • ehr_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_does_not_exist

get_versioned_ehr_status (
an_ehr_id: UUID[1]
): VERSIONED_EHR_STATUS
Pre_has_ehr: has_ehr (an_ehr_id)

Get the VERSIONED_EHR_STATUS object from the EHR with id ehr_id.

Errors
  • ehr_does_not_exist

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

Get a particular version of an EHR Status object.

5.2.4. I_EHR_DIRECTORY Interface

Interface

I_EHR_DIRECTORY

Description

Operations on EHR directory, with implicit Contribution creation.

Functions

Signature

Meaning

create_directory (
ehr_id: UUID[1],
a_dir_struct: UV_FOLDER[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_does_not_exist

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

Create or update a directory from a complete structure. Preceding version must be supplied and correct if EHR directory already exists.

Errors
  • ehr_does_not_exist

Parameters
a_dir_struct

Directory structure with which to replace current structure.

delete_directory (
ehr_id: UUID[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)

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

Errors
  • ehr_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_does_not_exist

get_directory_at_time (
an_ehr_id: UUID[1],
a_time: Iso8601_date_time[1]
): FOLDER
Pre_has_ehr: has_ehr (an_ehr_id)

Get the version of the Directory extant at time a_time.

Errors
  • ehr_does_not_exist

Parameters
a_time

Time specifying the extant top version of the Directory.

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

Get a particular version of the EHR Directory.

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_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_comp_id: UUID[1]
): Boolean
Pre_has_ehr: has_ehr (an_ehr_id)

Return True if a Composition with identifier a_comp_id exists.

Errors
  • ehr_does_not_exist

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_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 (Result)

Create the first version of a new Composition.

Errors
  • ehr_does_not_exist

  • composition_already_exists

delete_composition (
an_ehr_id: UUID[1],
a_comp_ver_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_comp_id argument identifies the current top Composition Version.

Errors
  • ehr_does_not_exist

  • composition_does_not_exist

get_composition (
an_ehr_id: UUID[1],
a_ver_comp_uid: UUID[1]
): COMPOSITION
Pre_has_ehr: has_ehr (an_ehr_id)

Retrieve a Composition by the uid of its version.

Errors
  • ehr_does_not_exist

  • composition_does_not_exist

Parameters
a_ver_comp_uid

Uid of the VERSIONED_COMPOSITION.

get_composition_at_time (
an_ehr_id: UUID[1],
a_ver_comp_uid: UUID[1],
a_time: Iso8601_date_time[1]
): COMPOSITION
Pre_has_ehr: has_ehr (an_ehr_id)

Retrieve the Composition version from a Versioned Composition that was the top version at time a_time.

Errors
  • ehr_does_not_exist

  • composition_does_not_exist

get_composition_at_version (
an_ehr_id: UUID[1],
a_comp_ver_uid: UUID[1]
): COMPOSITION

Get a particular version of a Composition.

Parameters
a_comp_ver_uid

Uid of a VERSION in a VERSIONED_COMPOSITION.

get_versioned_composition (
an_ehr_id: UUID[1],
a_comp_ver_uid: UUID[1]
): VERSIONED_COMPOSITION
Pre_has_ehr: has_ehr (an_ehr_id)

Retrieve the VERSIONED_OBJECT of a Composition by uid.

Errors
  • ehr_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_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_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_does_not_exist

  • contribution_does_not_exist

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

List all available Contributions.

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: PARTY[1]
): UUID

Create a new Party.

create_party_relationship (
a_version: PARTY_RELATIONSHIP[1]
): UUID

Create a new Party Relationship.

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 in service.

get_party (
a_versioned_party_id: UUID[1]
): PARTY

Get the current Version of a Party.

get_party_at_version (
a_party_version_id: UUID[1]
): PARTY

Get a particular Party Version.

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.

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

Update a Party with a new Version.

delete_party (
a_versioned_party_id: UUID[1]
)

Delete an existing Party.

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_id: UUID[1]
): Boolean

Return True if Party relationship exists in service.

get_party_relationship (
a_versioned_party_id: UUID[1]
): PARTY_RELATIONSHIP

Get the current Version of a Party relationship.

get_party_relationship_at_version (
a_party_version_id: UUID[1]
): PARTY_RELATIONSHIP

Get a particular Party relationship Version.

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

Get the Version of a Party relationship current at a_time.

update_party_relationship (
a_versioned_party_id: UUID[1],
a_version: PARTY_RELATIONSHIP[1]
): UUID

Update a Party relationship with a new Version.

delete_party_relationship (
a_versioned_party_id: UUID[1]
)

Delete an existing Party relationship.

7. Query Package

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

7.2. Class Definitions

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

Errors

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.

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

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.

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

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

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

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

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

8. Admin Package

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

8.2. Class Definitions

8.2.1. I_ADMIN_SERVICE Interface

Interface

I_ADMIN_SERVICE

Description

Primary ADMIN_SERVICE Interface.

Functions

Signature

Meaning

list_contributions (
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.

contribution_count (
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 (
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 (
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.

physical_party_delete (
a_party: PARTY_REF[1]
)

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

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

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

Move selected Parties and relationships to archival storage.

8.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[0..1]
)

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

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.

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

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