Ocean Informatics EHR Service Interface

Introduction

The interface below is the current EHR service interface for the back end EhrBank component, within the Ocean Informatics openEHR-based EHR product.

StatusThis specification below is essentially complete, but some small details may be changed over time.

Design Concept

The service specified below is a coarse-grained, stateless service interface to an openEHR data store. EHRs are committed in Contributions, and accessed either as individual Compositions or via AQL Queries. The corresponds to a thin client calling a web service.

Paths and URIs

To be continued

Querying

To be continued

Authentication

Authentication is assumed to have taken place before any of these calls are made.

To be continued

Exception handling

Currently exceptions (e.g. user not authenticated etc) are not defined as part of this interface, but they could be.

To be continued

Specification

EHR Management

Description	Signature	Details
Create EHR	HierObjectId CreateEHR(EhrStatus ehrStatus, AuditDetails commitAudit)	Parameters ehrStatus: EHR status details of the new EHR, this may include the subject external reference commitAudit: Commit audit details of the EHR creation including the committer Returns EHR identifier
Find EHR	HierObjectId FindEHR(PartyRef subjectExternalRef)	Parameters subjectExternalRef: subject external reference Returns EHR identifier
Get EHR Status	Version<EhrStatus> GetEHRStatus(HierObjectId ehrId, string versionTime)	Parameters ehrId: EHR identifier versionTime: optional value representing the time of the latest version to be used in the query mnemonic (e.g. LATEST_TRUNK_VERSION) or date/time, default is LATEST_TRUNK_VERSION Returns Version of EhrStatus at specified version time

EHR Contributions

Description	Signature	Details
Commit Contribution	void CommitContribution( HierObjectId ehrId, AuditDetails commitAudit, OriginalVersion[] versions)	Parameters ehrId: Identifier of EHR to which the versions will be committed commitAudit: Commit audit details of the EHR contribution including the committer versions: list of original version objects being committed to an EHR, type of version data may be different to other items in list Returns void

Compositions

Description	Signature	Details
Find Compositions	ResultSet FindCompositions( HierObjectId ehrId, string[] compositionPaths, ArchetypeId compositionArchetypeId, string[] compositionCriteria)	Parameters ehrId: Identifier of EHR to which the versions will be committed compositionPaths: List of item paths within a composition to be returned in results compositionArchetypeId: optional composition archetype ID compositionCriteria: optional list of composition criteria as item path comparision expressions (e.g. context/start_time > '20120101') Returns The result set containing composition path column definitions and rows of items for each column
Get Composition	XVersionedObject<Composition> GetComposition(HierObjectId objectId)	Parameters objectId: Composition objectId (Versioned Composition UID) Returns Versioned composition with all versions
Get Composition	Version<Composition> GetComposition(HierObjectId objectId, string versionTime)	Parameters objectId: Composition objectId (Versioned composition uid) versionTime: optional value representing the time of the latest version to be used in the query mnemonic (e.g. LATEST_TRUNK_VERSION) or date/time, default is LATEST_TRUNK_VERSION Returns Version of composition at specified version time
Get Composition	Version<Composition> GetComposition(ObjectVersionId versionUid)	Parameters versionUid: Composition version UID Returns Version of composition with specified version UID

EHR Queries

Description	Signature	Details
Execute Query	ResultSet ExecuteQuery(string queryStatement, string versionTime)	Parameters queryStatement: AQL statement versionTime: optional value representing the time of the latest version to be used in the query mnemonic (e.g. LATEST_TRUNK_VERSION) or date/time, default is LATEST_TRUNK_VERSION Returns The result set containing optional column definition and rows of items for each column

Data Structures

ResultSet

XML schema data view

 <xs:complexType name="ResultSet">
  <xs:sequence>
   <xs:element minOccurs="0" name="name" type="xs:string" />
   <xs:element minOccurs="0" name="totalResults" type="xs:int" />
   <xs:element minOccurs="0" maxOccurs="unbounded" name="columns" nillable="true">
    <xs:complexType>
     <xs:sequence>
      <xs:element name="name" type="xs:string" />
      <xs:element minOccurs="0" name="path" type="xs:string" />
     </xs:sequence>
    </xs:complexType>
   </xs:element>
   <xs:element minOccurs="0" name="rows">
    <xs:complexType>
     <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="row">
       <xs:complexType>
        <xs:sequence>
         <xs:element minOccurs="0" maxOccurs="unbounded" name="items" nillable="true" />
        </xs:sequence>
       </xs:complexType>
      </xs:element>
     </xs:sequence>
    </xs:complexType>
   </xs:element>
  </xs:sequence>
 </xs:complexType>

C# / Java

The following is C#.Net code, the Java code will be very similar, with different ancestor classes providing iteration / list capabilities.

// a ResultSet has a name, a count of rows, its definition (list of columnDefs), and the row data
public class ResultSet
{
    string Name { get; set; }
    int TotalResults { get; set; }
    ResultColumnDef[] Columns { get; set; }
    ResultRow[] Rows { get; set; }
}

// the definition of the result set as a logical set of columns,
// mapped to archetyped data structures via paths
public class ResultColumnDef
{
    string Path { get; set; }    // an archetype or RM path
    string Name { get; set; }    // name of the column in this result set
}

// a row object from which cell objects can be obtained,  via either an integer index (0-based) or the column name
// Here, 'object' is the 'Any' object of the programming language; it can be anything from a String, Integer etc,
// to a DV_CODED_TEXT or other openEHR Data type, to an Observation or Composition, from the main openEHR RM.
// What the objects are is completely dependent on what the query paths refer to.
public class ResultRow
{
    object[] Items { get; set;}
}

Modes of access

Data in a ResultSet can be accessed in the following ways.

ResultSet results;

results.Rows[0].Items[0]                 // first row, first cell
results.Rows[5].Items[13]                // 6th row, 14th cell
results.Rows[0].Items["name/value"]      // first row, 'name/value' column