We'd like to migrate Reference Application (Ref App) to use openconceptlab.com (OCL) as the source of concepts. At the same time we'd like to set the path for managing concepts by other distributions.
Currently, the OCL has the latest CIEL dictionary loaded. It is possible to import all CIEL concepts into Platform using the openconceptlab module and get incremental updates whenever new versions of the dictionary are available.
The OCL groups concepts in SOURCES or COLLECTIONS. Every concept in OCL must be created under a SOURCE. For example CIEL concepts are created under the CIEL SOURCE.
COLLECTIONS, on the other hand, group references to concepts, which exist under different sources. It is currently possible to create a collection with references to concepts without specifying concept versions (the concept will be updated whenever it is updated in the source). In the future OCL plans to add support to include in collections:
- references to exact concept versions
- references to all concepts from a given source / given version of a source
- references to all concepts from a collection / given version of a collection
For Ref App we do not need the entire CIEL dictionary, rather a small subset of it and we do not want to introduce our own concepts. We can rely solely on using a COLLECTION, which has been created for that purpose at http://api.openconceptlab.com/orgs/openmrs/collections/reference-application/ (currently empty due to a bug in OCL preventing us from adding anything)
We will be able to subscribe to that collection the same way as we subscribe to the CIEL source using the openconceptlab module. In Ref App we will subscribe to the exact version of the collection. The export will be triggered before releasing Ref App and it will contain concepts in versions available at the time of export. The initial export file will be distributed with the referenceapplication-metadata module so that no connection to openconceptlab.com will be required.
When we release a new version of Ref App, we will export a new version of the collection from OCL with any new concepts and updates and replace the file in the referenceapplication-metadata module. The openconceptlab module will identify and import all concepts with newer versions.
At any given time you will be able to subscribe to one SOURCE or COLLECTION of concepts using the openconceptlab module. Basically if your distribution wants to rely entirely on the CIEL dictionary, you will subscribe to the CIEL SOURCE. If your distribution wants to add concepts from other sources or needs just a subset of the CIEL SOURCE, then you will subscribe to a COLLECTION created for your distribution.
That said if you start from Ref App, you can change to subscribe to the full CIEL dictionary or any other collection, which contains a subset of concepts required by Ref App. It is particularly important when you try to upgrade to a newer version of Ref App, at which point we will verify that you have all required concepts or the missing concepts can be installed without validation errors.
The workflow implies that the concept management will eventually be done exclusively on the OCL server. Currently, the OCL UI does not let you do much and for Reference Application we will focus on using the REST API. Also the OCL server doesn't have any validation yet so you may create sources or collections of concepts that include duplicate concepts and they may not import properly into Platform.
There is still a lot of pending work on the OCL server before concept dictionaries can be easily managed from there.
Right now we have a smaller goal for supporting Ref App. Over the next weeks I will work with Jonathan Payne to identify anything missing in OCL for that particular use case.
As always I'm looking for feedback and flaws in the workflow as described.