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