Ocean Informatics vEHR Service Interface

Introduction

EhrGate is the Ocean Informatics virtual EHR middleware component. It can be deployed server-side or client-side, and is fully compliant to openEHR release 1.0.2. It uses standards AOM 1.4 archetypes and Ocean templates, which will be migrated to the forthcoming openEHR template specification. The following interfaces reflect the API as of early 2010. Things that might be desirable to do in contributing to an openEHR vEHR specification:

  • don't include initialisation functions
  • reduce statefulness of the interface

Specification

Initialisation

Description

Signature

Details

Create EhrGate Instance
Creates an EhrGate instance with no session context

static
IEhrGate Create()

Returns
EhrGate object

Create EhrGate Instance With Session Context
Create new instance of EhrGate object that links to an
existing EhrGate session context. This allows multiple
instances of EhrGate to link to the same EhrGate session
context.

static
IEhrGate Create(string sessionTicket)

Parameters
sessionTicket: ticket of existing EhrGate session
Returns
EhrGate object

Authenticate User

string
AuthenticateUser(string userId,
                 string password)

Parameters
userId: user identifier
password: user password
Returns
authentication token

Session Management

Description

Signature

Details

Open SessionObtains a session in the server; creates an
EhrGate session proxy object containing the
id, and returns a ticket for subsequent
access to this object.

string
OpenSession(string userId,
            string authenticationToken)

Parameters
userId: user identifier used by EHR service to
 audit log all operations against the user
authenticationToken: authentication token returned
by AuthenticateUser or another agreed authentication token
Returns
session ticket identifying the new EhrGate session
(NOT equal to the EHR service session ID)

Close SessionUse the current EhrGate session ticket to call
EHR service CloseSession using the associated session ID.

void
CloseSession()

 

Record Management

Description

Signature

Details

Create EHR

HierObjectId
CreateEhr(EhrStatus ehrStatus,
          PartyProxy committer,
          PartyRef gatekeeper)

Parameters
ehrStatus: EHR status details of the new EHR, this may include the
external subject identifier and demographic source namespace identifier
committer: committing party that created the EHR
gateKeeper: details of the party responsible for allocating EHR access,
null indicates the EHR subject
Returns
EHR identifier

Find EHR

HierObjectId
FindEhrId(string subjectId,
          string subjectIdNamespace)

Parameters
subjectId: subject identifier within a demographic source
subjectIdNamespace: namespace identifier of the demographic source
Returns
EHR identifier

Open EHR

void
OpenEhr(HierObjectId ehrId)

Parameters
ehrId: Identifier of EHR to open an empty context

Use EHR

void
UseEhr(HierObjectId ehrId)

Parameters
ehrId: Identifier of EHR to set as current context

Close EHR

void
CloseEhr(HierObjectId ehrId)

Parameters
ehrId: Identifier of EHR to close

Contribution Management

Description

Signature

Details

Create Contribution
Create Contribution context

void
CreateContribution()

 

Has Contribution
Contribution context exists

bool
HasContribution { get; }

Returns
true when current EHR has a contribution context

Commit Contribution

void
CommitContribution(PartyProxy committer,
                   string comment,
                   DvCodedText changeType)

Parameters
committer: details of committing party
comment: description of contribution
changeType: type of change the contribution makes to EHR

Rollback Contribution

void
RollbackContribution()

 

Data Creation and Modification

Description

Signature

Details

Create New Composition

ICompositionBuilder
CreateComposition(string templateId)

Parameters
templateId: identifier of a template or archetype which will define the
type of the new composition
Returns
composition builder object

Create New Composition Data

ICompositionBuilder
CreateComposition(Composition composition)

Parameters
composition: openEHR composition data to be added to the existing
contribution
Returns
composition builder object containing the provided composition data

Modify Existing Composition

ICompositionBuilder
ModifyComposition(HierObjectId compositionId)

Parameters
compositionId: versioned composition identifier to be modified
Returns
composition builder for a revision of the composition populated
with preceding data

Modify existing composition against template

ICompositionBuilder
ModifyComposition(HierObjectId compositionId,
                  string templateId)

Parameters
compositionId: versioned composition identifier to be modified
templateId: identifier of template for validation
Returns
composition builder for a revision of the composition

Modify existing composition data

ICompositionBuilder
ModifyComposition(ObjectVersionId precedingVersionUid,
                  Composition composition)

Parameters
precedingVersionUid: version UID of preceding composition version
composition: composition data of the new composition version
Returns
composition builder for a revision of the composition populated with the
provided composition data

Replace existing composition

ICompositionBuilder
ModifyComposition(HierObjectId compositionId,
                  string templateId,
                  bool populateComposition)

Parameters
compositionId: versioned composition identifier to be modified
templateId: identifier of template for validation
populateComposition: false does not copy data from preceding version
Returns
composition builder for a revision of the composition

Delete Composition
Adds a new version, which doesn't have data,
of an existing composition into the current
contribution.

void
DeleteComposition(HierObjectId compositionId)

Parameters
compositionId: Versioned composition UID
Returns
The composition builder interface of the new composition version

Get candidate compositions

IResultSet
GetCandidateCompositions(string resultSetId,
                         string[] compositionPaths,
                         ArchetypeId compositionArchetypeId,
                         string compositionCriteria)

Parameters
resultSetId: identifier of resultset in EHR context
compositionPaths: paths of attributes to return
compositionArchetypeId: filter by composition archetype, null indicates no filter
compositionCriteria: filter by attribute criteria, null indicates no filter
Returns
table of composition attributes

Get Composition

IComposition
GetComposition(HierObjectId compositionId,
               string versionTime)

Parameters
compositionId: versioned composition identifier
versionTime:

  • 'latest_version' retrieves latest version,
  • 'all_versions' retrieves all version
    Returns
    specified version of composition or latest version when 'all_versions' are retrieved

Get composition version

IComposition
GetComposition(ObjectVersionId versionUid)

Parameters
versionUid: composition version identifier
Returns
specified composition

Fine-grained Content Creation

There are various ways to create the fine-grained content of Compositions in EhrGate.

  • The most basic way is to use the generic Composition building functions.
  • Another common way is via the use of a Template Data Object (TDO), which is a programming artefact generated from an openEHR template. This example shows its use.

Queries

 

 

 

Register Query
Register Query in Query Manager

void
RegisterQuery(string queryId,
              string queryStatement)

Parameters
queryId: identifier used to register query in Query Manager
queryStatement: Archetype Query Language statement

Has Registered Query
Query exists in Query Manager


bool
HasRegisteredQuery(string queryId)

Parameters
queryId: identifier used to register query in Query Manager
Returns
true if queryId exists in Query Manager

Query Compositions
Retrieves composition version result set for
specified "composition" query from EhrBank and
adds them to the current EHR context

string[]
QueryCompositions(string queryId)

Parameters
queryId: Identifer of the composition query to be executed
Returns
Set of composition identifiers fro the compositions retrieved

Execute predefined Query
Executes registered query or predefined EHR query
against current EHR and returns the results. The
registered AQL query corresponding to the given
queryId must have ehr_id predicate and the ehr_id
value specified in the query must be the same as
the current EHR ehr_id.
The results are maintained in the Virtual EHR
result sets collection. A current EHR must be in use.

IResultSet
ExecuteQuery(string queryId,
             bool replaceExisting)

Parameters
queryId: identifier of query to execute, results stored in EHR context using this identifier
replaceExisting: if result set exists, it is replaced with new results
Returns
table of selected data objects

Execute Query Statement
Executes specified query statement against current
EHR and returns the results.
The results are maintained in the Virtual EHR result
sets collection.
A current EHR must be in use. The query statement
must not contain parameters. The query must have
ehr_id predicate and the ehr_id value specified in the
query must be the same as the
current EHR ehr_id value.

IResultSet
ExecuteQuery(string queryId,
             string queryStatement)

Parameters
queryId: Query ID
queryStatement: AQL query statement with no parameters.
Returns
Results of the query

Run Registered Query
Executes a registered query or predefined EHR query.
Results are held on the server and are retrieved using
RetrieveResults. When a current EHR is not in use, a
registered query with no parameters must be specified.
When a current EHR is in use, the query must have
ehr_id predicate specified, such as
.. FROM EHR [ehr_id/value='xxx'],
and the ehr_id/value value must be the same as the
current EHR ehr_id value. If ehr_id/value value is a
parameter, then the value associated with the ehr_id
parameter must be the same as the current EHR
ehr_id.

int
RunQuery(string queryId)

Parameters
queryId: Identifier of a registered query or previously created EHR query
Returns
total number of results

Retrieve Query Results

IResultSet
RetrieveResults(string queryId,
                int maxResults)

Parameters
queryId: identifier of query results to retrieve
maxResults: number of results to return, 0 returns all results
Returns
next set of results until all retrieved