From 49acc0ba725d6a314fa7e122c9ae57e1544a9c98 Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:00:20 +0200 Subject: [PATCH 1/8] textual edits OpenEHR -> openEHR --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8288b978c..1ee785d99 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Archie: OpenEHR Library +# Archie: openEHR Library Archie is an openEHR Library written in Java, which can be used to implement openEHR tools and systems. See http://www.openehr.org for information about openEHR. Archie works with the most recent versions of openEHR. This includes ADL version 2. @@ -14,7 +14,7 @@ Version 0.4 of archie is a major update that requires changes in your code to up ## Dependency -You can depend on parts of Archie, or the entire library at once. If you want the entire library, including the Archetype Object Model, ADL parser, all tools and OpenEHR reference model implementation, you can do in gradle: +You can depend on parts of Archie, or the entire library at once. If you want the entire library, including the Archetype Object Model, ADL parser, all tools and openEHR reference model implementation, you can do in gradle: ```gradle dependencies { @@ -89,7 +89,7 @@ To install to your local maven repository for use in other gradle or maven proje ## Archetypes -The base of OpenEHR are archetypes. Archie allows you to work with them, and defines tools to create and validate them. +The base of openEHR are archetypes. Archie allows you to work with them, and defines tools to create and validate them. ### Parsing and Archetype queries @@ -148,7 +148,7 @@ The validation result contains the validation result, listing any errors in the ### Reference model metadata You may have noticed a call to ```BuiltinReferenceModels.getMetaModels()```. This retrieves the metadata for the reference models, which are needed to validate and flatten archetypes. Archie contains two types of metamodels: BMM, and reflection based metadata. -The BMM models are a file containing metadata in a form defined by the OpenEHR specifications. +The BMM models are a file containing metadata in a form defined by the openEHR specifications. The reflection based metadata contains ModelInfoLookup classes. They are derived from an implementation of a reference model. Note that the ModelInfoLookup classes are only added if you depended on them. If you depended on archie-all, you're all set. ### Operational templates From 85d12d3108d428fc3eca66493103f2a7cab55564 Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:04:22 +0200 Subject: [PATCH 2/8] OpenEHR -> openEHR --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1ee785d99..6d0f0a360 100644 --- a/README.md +++ b/README.md @@ -154,8 +154,8 @@ The reflection based metadata contains ModelInfoLookup classes. They are derived ### Operational templates You can create operational templates of your archetypes. Think of operational templates as something you generate from an archetype or template to more easily work with it. If you are creating an EHR implementation, these will likely be the most useful form of archetypes to work with. -OpenEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without operational templates, you would need to build support for these structures into all of your tools. Operational templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about operational templates, see (the documentation at the OpenEHR website)[http://openehr.org/releases/AM/latest/docs/OPT2/OPT2.html]. -Note that ADL 2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL 2 as templates in combination with the operational template creation. See (the OpenEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. +openEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without operational templates, you would need to build support for these structures into all of your tools. Operational templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about operational templates, see (the documentation at the openEHR website)[http://openehr.org/releases/AM/latest/docs/OPT2/OPT2.html]. +Note that ADL 2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL 2 as templates in combination with the operational template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. To create an Operational Template: @@ -343,7 +343,7 @@ public void walk(CObject cobject) { ## Reference Model tools -Archie contains an implementation of the OpenEHR reference model version 1.0.4. It does not yet contain the task planning part. It also contains tools to work with reference model objects. +Archie contains an implementation of the openEHR reference model version 1.0.4. It does not yet contain the task planning part. It also contains tools to work with reference model objects. ### Reference model object creation @@ -568,13 +568,13 @@ Note that it requires a MetaModels class. This contains the Metadata of the refe ### Reference Model Metadata -Archetype tools require metadata about the used reference model to operate. This can be the OpenEHR reference model, but it can also be something else. Archie has two concepts to define this metadata: Reflection based metadata and BMM metadata. Above is a short description of how to load the built-in metadata. This should be enough for most users. However, if you want to add new reference models or reference model metadata, you need this paragraph. +Archetype tools require metadata about the used reference model to operate. This can be the openEHR reference model, but it can also be something else. Archie has two concepts to define this metadata: Reflection based metadata and BMM metadata. Above is a short description of how to load the built-in metadata. This should be enough for most users. However, if you want to add new reference models or reference model metadata, you need this paragraph. The MetaModels class is an abstraction over these two types of models. Construct this, and it will automatically select the available metadata model. Note that if a BMM model is present for your archetype, it will use that if possible. -Reflection based metadata bases its metadata on an actual reference model implementation in Java. Two are included, the ArchieRMInfoLookup, for the OpenEHR Reference Model, and the TestRMInfoLookup, for the openEHR Test models. You can register these on a ReferenceModels class, see the code in the previous paragraph for an example +Reflection based metadata bases its metadata on an actual reference model implementation in Java. Two are included, the ArchieRMInfoLookup, for the openEHR Reference Model, and the TestRMInfoLookup, for the openEHR Test models. You can register these on a ReferenceModels class, see the code in the previous paragraph for an example -The BMM model is not based on an actual implementation, but on a file containing the metadata. The specifications of BMM are part of OpenEHR and can be found at http://www.openehr.org/releases/BASE/latest/docs/bmm/bmm.html. +The BMM model is not based on an actual implementation, but on a file containing the metadata. The specifications of BMM are part of openEHR and can be found at http://www.openehr.org/releases/BASE/latest/docs/bmm/bmm.html. To use, parse your own BMM files, then load the AOM Profiles. From 45bfe5b8694d4f03dee1f3b3cea0c4331f5c386a Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:08:21 +0200 Subject: [PATCH 3/8] adl 2 -> ADL2 https://specifications.openehr.org/releases/AM/Release-2.2.0/ADL2.html --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 6d0f0a360..b2cadca99 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Archie is an openEHR Library written in Java, which can be used to implement openEHR tools and systems. See http://www.openehr.org for information about openEHR. Archie works with the most recent versions of openEHR. This includes ADL version 2. -It contains an ADL 2 parser and an archetype object model implementation, as well as the EHR part of the reference model implementation. +It contains an ADL2 parser and an archetype object model implementation, as well as the EHR part of the reference model implementation. It uses the ANTLR adl-grammar written by Thomas Beale at https://github.com/openehr/adl-antlr. @@ -155,7 +155,7 @@ The reflection based metadata contains ModelInfoLookup classes. They are derived You can create operational templates of your archetypes. Think of operational templates as something you generate from an archetype or template to more easily work with it. If you are creating an EHR implementation, these will likely be the most useful form of archetypes to work with. openEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without operational templates, you would need to build support for these structures into all of your tools. Operational templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about operational templates, see (the documentation at the openEHR website)[http://openehr.org/releases/AM/latest/docs/OPT2/OPT2.html]. -Note that ADL 2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL 2 as templates in combination with the operational template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. +Note that ADL2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL2 as templates in combination with the operational template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. To create an Operational Template: @@ -450,7 +450,7 @@ The following features are experimental. This means its working or API will like ## Importing and converting ADL 1.4 files -Starting from version 0.7, Archie can import ADL 1.4 files, and convert them to ADL 2. To do so, do the following: +Starting from version 0.7, Archie can import ADL 1.4 files, and convert them to ADL2. To do so, do the following: ```java ADL14ConversionConfiguration conversionConfiguration = new ADL14ConversionConfiguration(); @@ -473,22 +473,22 @@ for(String file:fileNames) { ADL2ConversionResultList resultList = converter.convert(archetypes); for(ADL2ConversionResult adl2ConversionResult:resultList.getConversionResults()) { if(adl2ConversionResult.getException() == null) { - // convertedArchetype is the ADL 2 conversion result. Additional warning messages in adl2ConversionResult.getLog() + // convertedArchetype is the ADL2 conversion result. Additional warning messages in adl2ConversionResult.getLog() Archetype convertedArchetype = adl2ConversionResult.getArchetype(); } } ``` -The converted archetypes are now in ADL 2, differential form. Note that it's a good idea to run these trough the archetype validator, especially if they are specialized archetypes. tooling for ADL 1.4 specialized archetypes often has limited validations, meaning that they often contain errors. +The converted archetypes are now in ADL2, differential form. Note that it's a good idea to run these trough the archetype validator, especially if they are specialized archetypes. tooling for ADL 1.4 specialized archetypes often has limited validations, meaning that they often contain errors. In case an archetype has been specialized, you will need to supply both the specialized archetype and its parent to the converter at the same time to allow for conversion to succeed, otherwise there will be an exception in the ADL2ConversionResult. -In ADL 2, at some nodes node ids are required where they are optional in ADL 1.4. As a result, the converter needs to generate new id codes. This has not yet been standardized. This is the reason you cannot yet expect all tools to generate the exact same or even entirely compatible ADL 2 archetypes. So use this tool carefully. +In ADL2, at some nodes node ids are required where they are optional in ADL 1.4. As a result, the converter needs to generate new id codes. This has not yet been standardized. This is the reason you cannot yet expect all tools to generate the exact same or even entirely compatible ADL2 archetypes. So use this tool carefully. ### Storing the conversion log for later use -One use case of this converter is to integrate it in modeling tools, so that modeling can still be ADL 1.4, but the output can be both ADL 1.4 and ADL 2. To ensure the tool generates the exact same node ids even after edits in ADL 1.4, a conversion log is generated that is output as the result of the conversion. It can be used as the input for a next conversion of the same archetypes, to ensure the same node ids are generated for the same nodes. To do so: +One use case of this converter is to integrate it in modeling tools, so that modeling can still be ADL 1.4, but the output can be both ADL 1.4 and ADL2. To ensure the tool generates the exact same node ids even after edits in ADL 1.4, a conversion log is generated that is output as the result of the conversion. It can be used as the input for a next conversion of the same archetypes, to ensure the same node ids are generated for the same nodes. To do so: ``` ADL2ConversionResultList resultList = converter.convert(archetypes, resultList.getConversionLog()); @@ -498,7 +498,7 @@ The conversion log can be serialized to a file for storage using Jackson, so it ### Conversion Configuration -You may have noticed an instance of `ADL14ConversionConfiguration` in the previous example. In this configuration the mapping from term codes as used in ADL 1.4 to term URIs as used in ADL 2 can be specified. See the `ConversionConfigForTest.java` file for an example on how this works, and how this can be serialized to a file, and the file `/tools/src/test/java/com/nedap/archie/adl14/configuration.json` for an example of a simple serialized configuration that contains sane defaults for snomed, loinc and openehr URIs. +You may have noticed an instance of `ADL14ConversionConfiguration` in the previous example. In this configuration the mapping from term codes as used in ADL 1.4 to term URIs as used in ADL2 can be specified. See the `ConversionConfigForTest.java` file for an example on how this works, and how this can be serialized to a file, and the file `/tools/src/test/java/com/nedap/archie/adl14/configuration.json` for an example of a simple serialized configuration that contains sane defaults for snomed, loinc and openehr URIs. If you leave the configuration empty, the converter will fall back to a default URI conversion. From 038fd5738247d6fefe4187b0a1b6a923bbcf0c04 Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:13:31 +0200 Subject: [PATCH 4/8] add link to ADL2 specs and explain ADL2 abbreviation. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b2cadca99..7f7604033 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Archie: openEHR Library Archie is an openEHR Library written in Java, which can be used to implement openEHR tools and systems. See http://www.openehr.org for information about openEHR. -Archie works with the most recent versions of openEHR. This includes ADL version 2. +Archie works with the most recent versions of openEHR. This includes Archetype Definition Language version 2 (ADL2). See https://specifications.openehr.org/releases/AM/Release-2.2.0/ADL2.html for information on ADL2. It contains an ADL2 parser and an archetype object model implementation, as well as the EHR part of the reference model implementation. It uses the ANTLR adl-grammar written by Thomas Beale at https://github.com/openehr/adl-antlr. From 4a2b896024889697661ba2e5624c141452d385b8 Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:22:28 +0200 Subject: [PATCH 5/8] AOM textual edits https://specifications.openehr.org/releases/AM/latest/AOM2.html --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7f7604033..decdf454d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Archie is an openEHR Library written in Java, which can be used to implement openEHR tools and systems. See http://www.openehr.org for information about openEHR. Archie works with the most recent versions of openEHR. This includes Archetype Definition Language version 2 (ADL2). See https://specifications.openehr.org/releases/AM/Release-2.2.0/ADL2.html for information on ADL2. -It contains an ADL2 parser and an archetype object model implementation, as well as the EHR part of the reference model implementation. +It contains an ADL2 parser and an Archetype Object Model (AOM) implementation, as well as the EHR part of the reference model implementation. For more information on the AOM see https://specifications.openehr.org/releases/AM/latest/AOM2.html. It uses the ANTLR adl-grammar written by Thomas Beale at https://github.com/openehr/adl-antlr. @@ -14,7 +14,7 @@ Version 0.4 of archie is a major update that requires changes in your code to up ## Dependency -You can depend on parts of Archie, or the entire library at once. If you want the entire library, including the Archetype Object Model, ADL parser, all tools and openEHR reference model implementation, you can do in gradle: +You can depend on parts of Archie, or the entire library at once. If you want the entire library, including the AOM, ADL parser, all tools and openEHR reference model implementation, you can do in gradle: ```gradle dependencies { From 5b8404b6a2a818021cbf47bff1d452a75888d3f9 Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:23:47 +0200 Subject: [PATCH 6/8] update adl2 spec link to latest previous link was fixed to adl 2.2.0 release, which would require updating the link for every adl release. Which will probably be forgotten. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index decdf454d..c52983a49 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Archie: openEHR Library Archie is an openEHR Library written in Java, which can be used to implement openEHR tools and systems. See http://www.openehr.org for information about openEHR. -Archie works with the most recent versions of openEHR. This includes Archetype Definition Language version 2 (ADL2). See https://specifications.openehr.org/releases/AM/Release-2.2.0/ADL2.html for information on ADL2. +Archie works with the most recent versions of openEHR. This includes Archetype Definition Language version 2 (ADL2). See https://specifications.openehr.org/releases/AM/latest/ADL2.html for information on ADL2. It contains an ADL2 parser and an Archetype Object Model (AOM) implementation, as well as the EHR part of the reference model implementation. For more information on the AOM see https://specifications.openehr.org/releases/AM/latest/AOM2.html. It uses the ANTLR adl-grammar written by Thomas Beale at https://github.com/openehr/adl-antlr. From 8d2113e7b43736dd9892fe23a558a3b52cf33395 Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 08:44:00 +0200 Subject: [PATCH 7/8] Update opt spec link README.md Old link was 404 due to changed url (removed /docs) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c52983a49..ce12bfb0e 100644 --- a/README.md +++ b/README.md @@ -154,8 +154,8 @@ The reflection based metadata contains ModelInfoLookup classes. They are derived ### Operational templates You can create operational templates of your archetypes. Think of operational templates as something you generate from an archetype or template to more easily work with it. If you are creating an EHR implementation, these will likely be the most useful form of archetypes to work with. -openEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without operational templates, you would need to build support for these structures into all of your tools. Operational templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about operational templates, see (the documentation at the openEHR website)[http://openehr.org/releases/AM/latest/docs/OPT2/OPT2.html]. -Note that ADL2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL2 as templates in combination with the operational template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. +openEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without operational templates, you would need to build support for these structures into all of your tools. Operational templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about operational templates, see (the documentation at the openEHR website)[https://specifications.openehr.org/releases/AM/latest/OPT2.html]. +Note that ADL 2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL 2 as templates in combination with the operational template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. To create an Operational Template: From 901ca3a8d972f1678985f615a4c08a1052bc3e5c Mon Sep 17 00:00:00 2001 From: Joost Holslag Date: Sat, 6 May 2023 09:40:01 +0200 Subject: [PATCH 8/8] operational template -> Operational Template https://specifications.openehr.org/releases/AM/Release-2.2.0/OPT2.html --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ce12bfb0e..11b226de7 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ To install to your local maven repository for use in other gradle or maven proje + [Checking for parse errors](#checking-for-parse-errors) + [Creating an Archetype Repository](#creating-an-archetype-repository) + [Reference model metadata](#reference-model-metadata) - + [Operational templates](#operational-templates) + + [Operational Templates](#operational-templates) + [Terminology: texts, term bindings and descriptions for your archetypes](#terminology-texts-term-bindings-and-descriptions-for-your-archetypes) + [Diffing archetypes](#diffing-archetypes) + [Serializing to ADL](#serializing-to-adl) @@ -151,11 +151,11 @@ You may have noticed a call to ```BuiltinReferenceModels.getMetaModels()```. Thi The BMM models are a file containing metadata in a form defined by the openEHR specifications. The reflection based metadata contains ModelInfoLookup classes. They are derived from an implementation of a reference model. Note that the ModelInfoLookup classes are only added if you depended on them. If you depended on archie-all, you're all set. -### Operational templates +### Operational Templates -You can create operational templates of your archetypes. Think of operational templates as something you generate from an archetype or template to more easily work with it. If you are creating an EHR implementation, these will likely be the most useful form of archetypes to work with. -openEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without operational templates, you would need to build support for these structures into all of your tools. Operational templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about operational templates, see (the documentation at the openEHR website)[https://specifications.openehr.org/releases/AM/latest/OPT2.html]. -Note that ADL 2 operational templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL 2 as templates in combination with the operational template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. +You can create Operation Templates of your archetypes. Think of Operation Templates as something you generate from an archetype or template to more easily work with it. If you are creating an EHR implementation, these will likely be the most useful form of archetypes to work with. +openEHR Archetypes allow you to reuse structures inside your archetypes at several places. It also allows to embed other archetypes inside your archetype. Without Operation Templates, you would need to build support for these structures into all of your tools. Operational Templates fix this for you, by replacing the proxies for structure and embedded archetypes in the archetype with a copy of the actual embedded structure. For more information about Operation Templates, see (the documentation at the openEHR website)[https://specifications.openehr.org/releases/AM/latest/OPT2.html]. +Note that ADL 2 Operation Templates is fundamentally different from the ADL 1.4 OET/OPT format. What you used to achieve with OET/OPT is now built into ADL 2 as templates in combination with the Operational Template creation. See (the openEHR specification on templates)[http://openehr.org/releases/AM/latest/docs/ADL2/ADL2.html#_templates] on how to work with them. To create an Operational Template: @@ -182,7 +182,7 @@ ArchetypeTerm term = cobject.getTerm(); logger.info("and the archetype term text in Dutch is: " + term.getText()); ``` -This just works in all cases - with the normal terminology of an unflattened archetype and with component terminologies from operational templates. +This just works in all cases - with the normal terminology of an unflattened archetype and with component terminologies from Operation Templates. Of couse, you can also specify the language yourself: @@ -440,7 +440,7 @@ RMObjectValidator validator = new RMObjectValidator(ArchieRMInfoLookup.getInstan List validationMessages = validator.validate(operationalTemplate, rmObject); ``` -The RM Object validator only works on operational templates, not on differential or flattened forms of archetypes. You can create an operational template from any archetype see [Operational templates](#operational-templates). +The RM Object validator only works on Operation Templates, not on differential or flattened forms of archetypes. You can create an Operational Template from any archetype see [Operational Templates](#operational-templates). Note that it is possible the API of the messages is still unstable and will likely change in future versions.