OCL vs OpenMRS: What are the technical differences w.r.t. concepts?

I believe we are entering an era where OpenMRS Implementers will be leveraging more and more of OCL’s tooling (yay!! :tada: ). We want to be increasingly mindful of areas where we might be duplicating effort between the OCL frontend and the Dictionary Manager WebApp.

But first, it would be helpful to super clearly understand: What are the key technical differences between how OCL and OpenMRS handle concepts?

Based on some older documentation here and some helpful comments from @burke, it seems like there are a few things:

  1. What a “Dictionary” is (e.g. is it a source or a collection or both)

    • In OpenMRS: we introduced the idea of a “Dictionary” in the Dictionary Manager application, since it represents the main thing an implementer would care about (i.e. where you might have your own concepts, as well as concepts you use from other groups/people.)
    • In OCL: OCL’s domain model doesn’t actually have anything called a “Dictionary”. It has a “repository” which can be either a “source” or a “collection”.
  2. How a “relationship” is handled (e.g. a “mapping” vs an “answer”)

    • In OpenMRS: in OpenMRS there are strong relationships between concepts (e.g. a Question concept will have Answers, and a Set concept will have specific Set Members, etc)
    • In OCL: in the OCL API these relationships are treated as “mappings”, which are not so explicit.

@ibacher @suruchi @hadijah315 @jwnasambu @paynejd @jamlung @akanter @raff I have 2 questions for you:

  1. Do these both still seem accurate?
  2. Anything else? Are there other known major technical or semantic differences between how OCL and OpenMRS modelling of concepts?

A primary goal of the OpenMRS Dictionary Manager was to hide some of the complexity of OCL’s powerful metadata model. Within OCL’s world:

  • Source: where concepts and mapping are created. You can add concepts & mappings or even clone (make a copy of) someone else’s concept or mapping, but you cannot refer to other concept & mappings from within a source.

  • Collection: a set of references to concepts & mappings from sources and/or other collections. You can add a reference to whatever you want added to your collection, but you cannot create a concept or mapping within a collection. Any new concept, new answer, new set member, or new mapping must first be created in an OCL source before it can be referenced within a collection. For example, if you want to add a new answer to a concept, both the answer concept and the link between the question and answer (a Q-AND-A mapping) must first exist in a source somewhere so they can be referenced.

You can think of source & collection as albums and playlists, respectively. Artists only create songs on albums; they don’t release a new song on your playlist. Your playlist can be a collection of songs from any album (or, in this case, parts of other playlists), but you can’t create a brand new song (that doesn’t come from an album) in your playlist.

The reason an OpenMRS Dictionary needs both an OCL collection and source is because we want to get to a place where people are re-using existing concepts (e.g., CIEL) for the majority of needs and only creating new content when really necessary. But when any new content is created (a concept, adding an answer, adding a set member, adding a mapping), this new content must first be added to a source before it can be referenced within the collection. The Dictionary Manager helps protect users from this complexity.

Correct. OpenMRS treats answers & set members as first-class properties of a concept and OCL just treats these as additional relationships between concepts (mappings). The modeling differences are less of an issue here, but the steps needed to edit a concept’s answers or set members highlights the differences. For example, here are the steps to add a new answer to an existing question concept (adding a new set member would be similar):

  1. Create new answer concept.
  2. Add answer to question concept.
  1. Create new answer in source.
  2. Create Q-AND-A mapping from question to answer within source.
  3. Add reference to new answer in collection.
  4. Add reference to Q-AND-A mapping to collection.
  • The concept “id” in OCL represents the concept “Code”; whereas, in the OpenMRS database, the concept “id” is sometimes used as a code (for small implementations with a single server), but is really an internal database identifier subject to change. This primarily applies to importing concepts from OpenMRS to OCL, where we will need a more reliable way to declare the official concept code for each concept (e.g., current proposal is to create a new “CODE” mapping type).

  • Several properties specific to OpenMRS concepts (e.g., ranges, “allow precise” for numerics, sort weights, etc.) are handled as “extra” key/value properties in OCL. This is working fine at the moment, but there’s nothing in OCL (other than the OpenMRS Dictionary Manager) that knows about these properties (their requirements, constraints, etc.).

  • OpenMRS does special handling of some map types. We’ve already mentioned answers & concept sets (only mappings in OCL), but SAME-AS is used to identify concepts by mappings from forms, reports, etc. and we will likely be adding a new CODE map type that OpenMRS will use to define the concept “Code” (OCL’s concept ID) outside of OCL. OCL doesn’t have any map type-specific behavior (all map types are treated the same). So, knowing concept are equivalent because of SAME-AS mapping or the special handling of Q-AND-A and CONCEPT-SET map types are all handled by the OpenMRS Dictionary Manager.

  • Validation rules. OCL does have support for custom validation schemas and we are recommend using it for OpenMRS sources & collections; however, there are no doubt some aspects of content validation that OpenMRS Dictionary Manager is handling that might not be handled by OCL. The easiest example I can think of is the previously mentioned “extra” properties (normal ranges, allow precise, sort weight, etc.).

I wrote up something about these conventions on the Wiki.

Probably worth noting that this currently isn’t implemented in the OCL module.

1 Like