openEHR-SDK

Java/Groovy Support of openEHR Operational Templates, Refernce Model, Data Generators and other tools for www.CaboLabs.com projects.

This will be used in CaboLabs apps like EHRGen, EHRServer, EMRApp and XML Rule Engine.

Build

The build was tested with Gradle 6.4.1 installed from SDKMAN!.

This generates a fat jar with all dependencies to simplify CLI command execution.

$ cd openEHR-SDK
$ gradle clean fatJar

Normal build without fat jar, for instance for running the tests.

$ cd openEHR-SDK
$ gradle clean build

Build without running the tests (faster).

$ cd openEHR-SDK
$ gradle build -x test

Requires Java 8+ and Groovy 2.5.5+

Also tested with JDK 11.0.x and Groovy 3.0.x.

For running tests, there are many options, examples below:

1. Run specific test case from a specific suite
2. Run all tests from a specific suite
3. Run all suites in a package
4. Run all tests

$ cd openEHR-SDK
$ gradle test --tests com.cabolabs.openehr.opt.OPTParserTest.testCompleteOPT
$ gradle test --tests com.cabolabs.openehr.opt.OPTParserTest
$ gradle test --tests com.cabolabs.openehr.opt*
$ gradle test

The test report in HTML will be under ./build/reports/tests/test/index.html

Command Tools (CLI)

Check the version of the build in gradle.properties, that should be x.y.z

uigen: Generate UI for data input

$ java -jar build/libs/opt-x.y.z.jar uigen path_to_opt dest_folder

Or shorthand (remember to update the x.y.z in the sdk.sh script):

$ ./sdk.sh uigen path_to_opt dest_folder

ingen: Generate XML instances from OPTs with random data

$ java -jar build/libs/opt-x.y.z.jar ingen path_to_opt dest_folder [amount] [json|xml] [version|composition] [withParticipations]

1. amount: defines how many XML instances will be generated, default is 1
2. format: 'json' or 'xml', default is 'json'
3. object: type of openEHR object to generate, 'version' or 'composition', default is 'version'
4. withParticipations: if included in the parameters, it will add participations to the composition

inval: Validate XML or JSON instances against the schemas

NOTE: If the 'semantic' keyword is specified as an argument, this tool will try to load the referenced OPT and validate against it's constraints. The OPT will be loaded from src/main/resources/opts/com.cabolabs.openehr_opt.namespaces.default so if you want to validate a new instance, you need to put the OPT there first.

Validate one instance:

$ java -jar build/libs/opt-x.y.z.jar inval path_to_xml_or_json_instance [semantic]

Validate all instances in folder:

$ java -jar build/libs/opt-x.y.z.jar inval path_to_folder_with_xml_or_json_instances [semantic]

Note: if the folder contains JSON and XML, it will validate both with the correct schema, but the files should have .json or .xml extensions for the mixed validation to work OK.

In both cases, the output is "file IS VALID" or the list of validation errors if the file is not valid against the schemas.

trans opt: Transform an OPT in it's antive XML form to JSON

$ java -jar build/libs/opt-x.y.z.jar trans opt path_to_opt destination_folder

trans composition: Transform an COMPOSITION instances between canonical XML and JSON formats

To transform a XML COMPOSITION to JSON:

$ java -jar build/libs/opt-x.y.z.jar trans composition path_to_compo.xml destination_folder

To transform a JSON COMPOSITION to JSON:

$ java -jar build/libs/opt-x.y.z.jar trans composition path_to_compo.json destination_folder

Note: the transformation of COMPOSITIONS between foramts relies on the file extension, only .xml or .json files are allowed.

Generate an OPT from ADL

This is a very important tool that allows you to generate a full blown Operational Template from a single ADL archetype. A common use case is for demographic archetypes to quickly test templates based on them, also for single archetype models like FOLDER and EHR_STATUS.

$ java -jar build/libs/opt-x.y.z.jar adl2opt path_to_adl dest_path

Use as Java/Groovy library

Validate an openEHR Operational Template against it's schema

def inputStream = this.getClass().getResourceAsStream('/xsd/OperationalTemplateExtra.xsd')
def validator = new XmlValidation(inputStream)

def path = "someopt.opt"
def f = new File(path)
if (!f.exists())
{
   println path +" doesn't exist"
   System.exit(0)
}

validateXML(validator, f)

static boolean validateXML(validator, file)
{
   boolean isValid = true
   if (!validator.validate( file.text ))
   {
      println file.name +' NOT VALID'
      println '====================================='
      validator.errors.each {
         println it
      }
      println '====================================='
      isValid = false
   }
   else
   {
      println file.name +' VALID'
   }

   println ""
   return isValid
}

Parse an openEHR Operational Template

OperationalTemplate loadAndParse(String path)
{
   def parser = new OperationalTemplateParser()

   def optFile = new File(getClass().getResource(path).toURI())
   def text = optFile.getText()

   return parser.parse(text)
}

To add the atttributes that are in the openEHR Reference Model but are not in the source OPT file, use the method complete():

def opt = loadAndParse("vital_signs.opt")
opt.complete()

Parse a JSON COMPOSITION

String path = "vital_signs.json"
File file = new File(getClass().getResource(path).toURI())
String json = file.text
def parser = new OpenEhrJsonParser()
Composition c = (Composition)parser.parseJson(json)

Serialize a COMPOSITION to JSON

Composition compo = ...
def serializer = new OpenEhrJsonSerializer()
String json = serializer.serialize(compo)

Parse a XML COMPOSITION

String path = "vital_signs.xml"
File file = new File(getClass().getResource(path).toURI())
String xml = file.text
def parser = new OpenEhrXmlParser()
Composition c = (Composition)parser.parseLocatable(xml)

Serialize a COMPOSITION to XML

Composition compo = ...
OpenEhrXmlSerializer marshal = new OpenEhrXmlSerializer()
String xml = marshal.serialize(compo)

Validate COMPOSITION against OPT

// setup OPT repository
String opt_repo_path = "opts"
OptRepository repo = new OptRepositoryFSImpl(getClass().getResource(opt_repo_path).toURI())
OptManager opt_manager = OptManager.getInstance()
opt_manager.init(repo)

// load COMPOSITION
Composition compo = ...

// the validator automatically gets the tempalte from the repo based on the template_id in the COMPOSITION
RmValidator validator = new RmValidator(opt_manager)
RmValidationReport report = validator.dovalidate(compo, OptManager.DEFAULT_NAMESPACE)

report.errors.each { error ->
   println error
}

Transform XML COMPOSITION to JSON

String xml = ...
def parser = new OpenEhrXmlParser()
Composition c = (Composition)parser.parseLocatable(xml)
def serializer = new OpenEhrJsonSerializer()
String json = serializer.serialize(c)

Transform JSON COMPOSITION to XML

String json ...
def parser = new OpenEhrJsonParser()
Composition c = (Composition)parser.parseJson(json)
def serializer = new OpenEhrXmlSerializer()
String xml = serializer.serialize(c)

Generate JSON COMPOSITION from OPT

def opt = loadAndParse('vital_signs.opt')
def igen = new JsonInstanceCanonicalGenerator2()
String json = igen.generateJSONVersionStringFromOPT(opt, true, true)

Generate XML COMPOSITION from OPT

def opt = loadAndParse('vital_signs.opt')
def igen = new XmlInstanceGenerator()
String xml = igen.generateXMLCompositionStringFromOPT(opt, true)