Tools used to transform data source to a canonical JSON

Hello everybody,

I’m new to openEHR. I studied openEHR specification and I started playing around with opensource tools that are available.
I would like to get informations, from your experience, about tools used to transform data source format (CDA for example) to a canonical JSON composition. And if possible with a nice interface to do the mapping :slight_smile:
I had read some topic in the forum such as:
Graphical data mapping tools supporting openEHR?
HL7 V2 to OpenEHR
And I understand that Mirth and LinkEhr seems to be used. Do you know others?

From my comprehension, any integration engine which can handle JSON format or XML should be able to do the transformation.

I also read that some of you prefer to perform this mapping directly in the code. In this case, is there a must library to use?

Thank you for your answer.


Hi @lbettini

I don’t know if there is any tool available specific for this.

My personal opinion is mapping model to model, not instance to instance. In CDA, following good practices, there should be an Implementation Guide document that says how to structure each type of CDA. In openEHR that is done in a Template. So I would read the IG and map to a corresponding Template. Then implement the mapping rules. For instance, if my goal is integrating two systems in a network, I would do that implementation in an Integration Engine like Mirth Connect. For transforming documents at rest, I would use some mapping library or a language with good support for XML/JSON, but following the same mapping rules designed before.

The point is: it’s difficult to have a tool that maps any CDA to an openEHR COMPOSITION or vice versa, it’s something that should be done case by case, for each type of CDA (or whatever input model you have) to a specific openEHR Template.

Hope that helps.


Hi Pablo

Thank you very much for your answer, very clear

Have a nice day

Adding to what Pablo said and regarding:

Depending on your actual use-case, it might make sense to have a look at parsing the input with whatever library is suitable and create the output with either Better’s (ehr-common and web-template) or EHRbase’s (openEHR SDK) open source tools.

Additionally, you could explore the FLAT format (+ web template) as alternative to the canonical JSON (again, depends on your use-case). In simple transformation code it might be easier to create simple 1-level key/value pairs and render them as JSON, instead of manually keeping track of JSON trees.
Example FLAT I created in a test:

1 Like

Hi Jake

Great! I will have a look.
Thank you for your answer

@pieterbos & Co at Nedap: Can GitHub - openEHR/archie: OpenEHR library implementing ADL 2, AOM 2, BMM, RM 1.0.4 and many tools also be used in the approach suggested by @jake.smolka?

1 Like

Totally, thanks! (First day after paternity leave, sorry Pieter! :grimacing:)

Thaks Jake,

That is exactly the approach we have taken, including with the One London UCP import of legacy data via xml export files from the original system, mapped to a set of FLAT format compositions.

All of the integrators we have worked with use some form of tool like Mirth, albeit a fair bit of coding does need to be done within that environment, mostly because of the variability of incoming data, or tot convert term codings.


We use Mirth to ingest data, including simple file data exports from legacy systems as well as the traditional HL7 imports for data like lab reports. You can use whatever tool you are experienced with, we have a great Mirth engineer so its an easy choice for us. I also have to do some manual stuff, which I do in C#, its a bit tedious but once you have done it you understand composition formats to a whole new level !!!

1 Like

Hi, consider also flatehr , a tool for converting xml/json data to flat format compositions that you can then upload using REST. Basically you have to write a YAML with the mapping between XMLPATH/JSONPATH and the paths in the expected flat composition.

1 Like

No worries @lbettini

BTW I remembered I did a video a while ago about mapping openEHR <=> FHIR using Mirth Connect, this might help you since the process is very similar to CDA <=> openEHR, though instead of the Implementation Guide in FHIR you have Profiles FHIR to openEHR mappings using Mirth Connect - YouTube

For me using Mirth Connect for these kinds of transactional integrations (this is not a bulk migration) is natural since I’ve been using Mirth since 2007, back then we used to integrate systems by implementing IHE PIX and PDQ profiles. Though at the time I did that video about FHIR, they had the FHIR extension freely available and it’s not free anymore.

There is another tool I use to design the mappings, which is an archetype flatten tool that generates a CSV from an openEHR archetype, that is in the openEHR Toolkit

You can open the CSV, in Excel for instance, and start mapping there to your CDA (or whatever) fields. That spreadsheet could be your mapping rules spec that you use later as a guide for implementing the rules.

Another tool I use from the Toolkit is the openEHR JSON instance generator, which is also used in the video, that generates an openEHR canonical document from it’s definition, which is an openEHR Operational Template.

If you need to parse JSON, serialize to JSON, validate an openEHR composition, etc. you can use our Groovy implementation of those tools which is open source GitHub - ppazos/openEHR-OPT: Java/Groovy Support of openEHR Operational Templates, Refernce Model, Data Generators and other tools for projects

Hope that helps!


1 Like

Thank you all for your response. This gave me a good overview of tools / libraries available in openEHR to perform such a transformation.

1 Like