This guide will help you understand how to store clinical data in the EHRServer, using the commit service, and diferent ways to test that service.
This guide will show how to work with Operational Templates (OPT) to generate and send data to the EHRServer. The main role of the EHRServer is clinica data storage, so the data commit service is one of the most important functionalities of the EHRServer, and it's key to know how it works in order to use the EHRServer successfully.
These resources will help you test the data commit to the EHRServer:
The Operational Templates are definitions of clinical documents that follow the openEHR standard. The EHRServer uses OPTs to understand the structure and constraints of each clinical document. All clinical documents committed to the EHRServer should comply with one OPT.
You can create your OPTs using tools like Archetype Editor + Template Designer, or LinkEHR.
For now we will just use the ones created by CaboLabs for testing purposes. You can get the OPTs from here:
At CaboLabs we created this tool to help us on working with Operational Templates and to help
us testing the EHRServer. This tool is open source and free to use. We will use it to generate
clinical documents with dummy data that comply with an OPT. And we will use those documents to
test the commit service on the EHRServer's REST API. Download or clone the whole project. You
will need Java 7 or superior, and Groovy
to run it. When you have Groovy installed and the openEHR-OPT project downloaded and uncompressed, change
the opt.bat file with the path where you have Groovy. The openEHR-OPT project is here:
If you run opt.bat from the console and you get a "usage" message, the tool is working OK.
Insomnia is a great tool for testing REST APIs, we use is a lot to test the EHRServer's REST API.
On this guide we will use Insomnia as one of the two methods to commit clinical data to the EHRServer.
Since we use Insomnia to test the EHRServer's REST API, we created a script that has all the calls
to the API. You can use it to authenticate and commit data. Just download the script from the link
below and import it on Insomnia. If you see the API requests on the left menu, the import worked OK!
All the requests will be grouped by a Request Group called "EHRServer local".
This is a web app we developed to help us test the data commit to the EHRServer, and will be our
second method to test how to send data to the EHRServer. Since this is a web app, it has some
requirements. First you'll need to have Java 7 or superior. Second you'll need to download and
install Grails v2.5.5 (https://grails.org/download.html). It needs to be v2.5.5!. It can also be
installed through SDKMAN, check that on the download page. Once you have Grails installed, download
or clone the EHRCommitter project from here:
For the test we will use the staging server (https://ehrserver-cabolabs2.rhcloud.com/login/auth). Please create an account to setup your username, password and organization.
First, check that the Insomnia script you imported is pointing to our staging server. Go to the Request Group "EHRServer local", click on the down arrow that appears on the right, click on "Edit Environment". It will show a JSON with a lot of URLs, be sure that the one called exactly "base_url" has the value "https://ehrserver-cabolabs2.rhcloud.com/api/v1".
Then check that your credentials work. Go to the "login" request under the "EHRServer local" Request Group, click on it, click on "PARAMS", and change the data there with your credentials (username, password and organization number). Keep the "format" as JSON. Finally, click on "Send" on the opt right of the window. The RESPONSE should show you a token if the login was correct. Copy the value of the token, we will use it for the commit.
Now we will prepare our commit request. Go to the "commit empty versions" request, when you put the mouse over it you will see a gear, click on it, then click "Duplicate". We will use this copy as our test request. Rename the copy as "commit test 1". With the new request selected, go to the HEADERS tab and paste the token you copied from the login response. Note that the value of the "Authorization" header should be "Bearer _your_token_". We will leave this request as it is. Now we will focus on creating an EHR to commit the data to and a clinical document that will contain the data. With those elements our request will be complete.
To create an EHR, go to the staging server and login. Go to the EHRs section and click on "Create EHR". Just fill in anything to the Subject ID (external patient ID) and click on Save. The EHRServer will assign an UID to the EHR, copy it. Go back to Insomnia, select the "commit test 1" request, and go to the PARAMS tab. Paste the value of the EHR UID in the ehrUid param.
Finally we will create a sample document with dummy data to commit it to the EHRServer. First choose one of the OPTs downloaded on the first step and put it on a simple path like "C:\opts". The open a console, go to the folder where the openEHR-OPT is, and run this command:
Explanation of the command:
- main command
- action of generating a clinical document instance from an OPT
- OPT to be used to define the structure of the instance generated
- destination folder, where the instance will be stored
- number of instances that will be generated, you can create more instances and do a heavy load test
- is the structure that will be generated, "version" is a clinical document with versioning information, "composition" is a clinical document without the versioning info, and "version_committer" is a version with metadata to be used on the EHRCommitter (we will see that later).
The command will generate a file like this: C:\opts\Review_20170216011540_1.xml (OPT_date_instanceNumber.xml).
Open the generated file and copy it's content. It should start with <version xmlns=...>. Go back to Insomnia,
go to the "commit test 1" request, and click on the BODY tab. You will see that the body has a <versions xmlns...>
XML node. Paste the XML from the clinical document between the <versions> ... </versions> tags. You will end up
with something like this:
<versions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.openehr.org/v1"> <version xmlns="http://schemas.openehr.org/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ORIGINAL_VERSION"> <contribution> .... </version> </versions>
<versions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.openehr.org/v1"> <version xsi:type="ORIGINAL_VERSION"> <contribution> .... </version> </versions>
This is because a commit can contain many clinical documents. We will explain the use case of that in another guide. For now we will commit just one document (or one version).
Now our request is complete! Click on "Send" to test it and check the response.
If the response looks like the XML below, it means your commit was accepted:
<result> <type>AA</type> <message>Se han recibido correctamente todas las versiones para el EHR c35dfe02-4ece-465e-9433-0540c6d95f3f</message> </result>
Go to the EHRServer Web Console to verify the commit. After you login into the staging server, go to EHRs, click on the EHR that you used for the commit. Below the EHR data you will see a list of Contributions that represent all the changes to that EHR. The latest contribution should be our test. If you click over the XML icon, you will see exactly the same XML generated from the openEHR-OPT project, and if you click on the file icon, you will see the contents of the clinical document in a human-friendly format, but since the data is autogenerated, it will not make much sense. You can modify the data in the XML to make it more realistic.
Congratulations, you committed clinical data to the EHRServer!
Note: you will not be able to commit the same clinical document twice, since the EHRServer will consider that as a duplicate. What you can do is generate more instances in the openEHR-OPT and commit one by one, or you can change the contribution id and version uid in order to avoid the duplication check.
Generating the clinical document with annotations
This part assumes you already have a user created on the staging server and that you created an EHR (see previous section).
In the previous section we used the openEHR-OPT tool to generate a clinical document in XML (formally an openEHR VERSION instance). We used this command:
Now we are going to use the same command changing the last parameter to "version_committer".
This will generate an XML like before, but it will have metatags instead of data. For example the element a) of the previously generated XML, will look like b) in the one with metatags. See below:
<contribution> <id xsi:type="HIER_OBJECT_ID"> <value>a48e6a8c-a03e-4b04-bcff-54f806337f64</value> </id> <namespace>EHR::COMMON</namespace> <type>CONTRIBUTION</type> </contribution>b)
<contribution> <id xsi:type="HIER_OBJECT_ID"> <value>[[CONTRIBUTION:::UUID:::ANY]]</value> </id> <namespace>EHR::COMMON</namespace> <type>CONTRIBUTION</type> </contribution>
Let's say you installed the EHRCommitter in "C:\committer", copy the generated XML to "C:\committer\sample_instances".
Now let's run the EHRCommitter. Open a console, go to "C:\committer" and execute "grails prod run-app". Of course this supposes that you have Grails 2.5.5 and the EHRCommitter installed. The application will run on: http://localhost:8080/EhrCommitter
Open the address of the committer in your browser and login with your credentials from the staging server. The EHRCommitter uses the REST API of the EHRServer to authenticate the user and get the EHRs you created from the Web Console. The EHRCommitter will display a list of all the instances with metatags, you will see the one we created on the previous step. Click on that one.
A form with random data is displayed. Each field is defined by one metatag in the XML. The first field is a selector, click on it to select the EHR that you want to commit data to. That is the EHR you created from the Web Console. Then you can change the data on the form fields and submit it. The submit will take your data, create a valid VERSION instance in XML, and commit that instance to the EHRServer like we did from the Insomnia REST Client on the previous section, but now the commit is done by an app.
The nice thing about using the EHRCommitter is that you can generate as many commits and all will have different IDs/UIDs and data. When testing with Insomnia, you need to manually change the IDs and data if you want to commit two or more documents. On the other hand, this process requires to install more software than the Insomnia test.
Go to the staging server to check your commits!