What is the OpenMRS policy for Concepts' External IDs?

Hi @burke & @dkayiwa,

@suruchi and I are often creating concepts in OCL to support the O3 RefApp and other projects (eg ANC DAK project) - at least wherever it’s not practical to leverage a standard like CIEL.

When we create a concept, there are 2 types of IDs:

  • Concept ID
  • External ID

It is up to each organization to decide what they use as their External ID. We don’t currently have an “OpenMRS RefApp standard” way of structuring these Ext IDs. E.g. I have sometimes just re-written the concept name, like “hypertension-test”. This is now coming up for us in the ANC DAK project, where we are sometimes creating codes for items like ANCB10DE73

Should we be using something really fancy like the UUID generator tool? https://www.uuidgenerator.net/

@akanter & @burke what is the suggested best-practice for structuring your External IDs, in general? @jamlung it would be great for a summary of best-practice guidance to be available in a Help icon for the External ID field. And shouldn’t the External ID field be a required field?

1 Like

Shouldn’t External ID = Concept ID?


OCL stores OMRS UUIDs for all resources (excluding lookup tables) in an external_id field (e.g. OMRS.concept.uuid = OCL.concept.external_id)

@grace Currently, OCL suggests the following when you’re creating a source: image

This means that when you create either a concept or a mapping, you can tell OCL to auto-assign its ID as a sequential number (i.e. 1, 2, 3…) and the external_ID as a UUID. The main problem of this is that you have to do this when you create the source - you can’t apply this setting on an already existing source.

Not sure what OpenMRS’ rule on external IDs is, as far as whether it should or should not be required.

At least for concepts, they are required. Other types of data that external ids can be attached to (concept names, concept mappings, sources, etc.) they are optional. They should definitely be real UUIDs if that’s at all possible. At the very least, they need to be 36 characters long for everything to function as expected.

OpenMRS UUIDs are stored as “external identifier” within OCL. You shouldn’t be making up values for external identifier within OCL. If you are importing content from OpenMRS, the external identifiers will be populated with UUIDs. If you are creating new content for OpenMRS within OCL, then you should be using the OpenMRS Custom schema and set identifiers & external identifiers to be auto-generated as sequential numbers & UUIDs, respectively as Joe’s screenshot shows.

If you are working within a source that hasn’t been set to automatically assign UUIDs for new external identifiers and you’re creating new content, I’d recommend using an online Version 4 (Random) UUID generator like uuidgenerator.net to generate valid UUIDs and to ensure your universally unique identifiers are truly universally unique.

In OCL “external identifier” signifies an identifier used by the source other than the concept code (aka concept ID). They are “external” from OCL’s perspective, but from OpenMRS’ perspective, these are OpenMRS UUIDs, which should be version 4 random UUIDs.

Concepts IDs are namespaced within the source, meaning they are expected to be unique within the source but aren’t universally unique. For example the code “E08” may refer to diabetes in ICD-10, it’s also used as a washing machine error code, a model of Canon camera, and a color of brown.

I think a bigger question is what we plan to do with duplicate concepts created from a non-standard source (as the WHO ANC DAK are). In this case, I think it would be a strongly wrong direction to create a new source with duplicate concepts from SNOMED, CIEL, etc. Instead, we should leverage curated mappings from existing source concepts to the ANC guidelines. I have added those maps to the current CIEL source. This is a non-sustainable solution, however… although more appropriate than creating entirely new concepts to support the DAK.