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

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

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

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

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

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