$cascade for OpenMRS - Automatically add sets (answers, labsets, etc) when parent concept is added to my collection

[gracepotma]

As a user assembling a collection using the OCL Online UI, I want it to be fast to add sets of things into my collection (e.g. a Question with many connected answers; a LabSet ("panel") with many connected labs), so that I can "Add to Collection" a panel concept like CBC (Complete Blood Count #1019) and automatically have all the relevant labs in that panel also added to my collection (e.g. Hematocrit, Platelets, Hemoglobin, etc).

I actually expected this was already the case because when I click "Add to Collection" I see the modal that confirms that it will "Automatically add associated mappings":

(e.g. see 5 min clip of user testing adding a LabSet to a collection here: https://www.loom.com/share/d841edce17b547f8a5a922ed423ce1cd)

[paynejd]

Thanks for creating this ticket @gracepotma!

OCL has a feature (that the Dictionary Mgr uses) to "cascade source mappings", which means that when you add a concept, you have the option to also add any mappings from the same source where the concept you're adding is the fromConcept -- but it doesn't actually add any of the toConcepts. That said, this is an important feature to support, and we'll use this ticket to compile requirements.

• Embed cascade parameter in the reference: We want the ability to control cascading within each individual reference (instead of in the PUT request, which is the current behavior). Embedding the cascade parameter in the reference means that it will be saved along with the reference, which means that we can re-evaluate the reference in the future. It also means that each reference can have its own cascade parameter, rather than having to split different cascading behavior into separate requests.
• Add new cascade options: We want to support two types of cascading (maybe more in the future):
  • sourceMappings: Adds mappings from the same source where the concept to be added is the fromConcept
  • sourceToConcepts: Same as above, but it also adds the toConcepts if they are also from the same source
• Filter cascade by mapType: For both cascading methods, we want the ability to only cascade mappings that match one of the provided map types.

Examples

• Just add a concept:

/orgs/CIEL/sources/CIEL/concepts/1234/

• Add a concept plus its direct mappings stored in the same source

/orgs/CIEL/sources/CIEL/concepts/1234/?cascade=sourceMappings

• Add a concept plus its direct mappings and toConcepts stored in the same source

/orgs/CIEL/sources/CIEL/concepts/1234/?cascade=sourceToConcepts

• Add a concept and cascade, but filter to only Q-AND-A and CONCEPT-SET mapTypes

/orgs/CIEL/sources/CIEL/concepts/1234/?cascade=sourceMappings&cascadeMapTypes=Q-AND-A,CONCEPT-SET
/orgs/CIEL/sources/CIEL/concepts/1234/?cascade=sourceToConcepts&cascadeMapTypes=Q-AND-A,CONCEPT-SET

Questions

• Embedding cascade in a reference breaks the model of a reference always being an API query that OCL can run; however, there are a lot of reasons that embedding it like this makes sense. Should we consider another model? Or, should we make it so that the OCL API supports this as a query, and that this is a rare request where we return a bundle of resources of different types?

cc @snyaggarwal

[snyaggarwal]

@paynejd sourceToConcepts is available on QA via UI and API both. Please check it out and provide feedback

[snyaggarwal]

Test to describe/document the behaviour

[jamlung-ri]

This is working pretty well, and we have a discussion topic on this for tomorrow's Arch call.

[jamlung-ri]

We had a Cascading discussion in today's Arch call, which lays out some more specific functionality for $cascade.

Highlight:

Proposed method: Implement a new $cascade operation that returns mixed resource types based on the parameters used

/orgs/CIEL/sources/CIEL/concepts/1234/$cascade?method=sourceToConcepts&cascadeMapTypes=SAME-AS&resourceTypes=concepts,mappings

Need to consider recursion and hierarchy, and how this aligns with FHIR $subsumes
Would maintain backwards compatibility until we retire the old-style cascade

[jamlung-ri]

@snyaggarwal I am going to put this back to In Dev for these changes. We also need to get feedback on the UI piece of this.

Since this is becoming a series of features, we probably need to create a specific epic for this and continue to track the features there.

[jamlung-ri]

Turning this into an epic and adding tickets to it

[jamlung-ri]

Closing this out since this functionality has been implemented in OCL for some time. Note that there will be an additional set of work for OCLv3, which will be documented here: https://docs.google.com/document/d/1nkSEU4qizs3fk6y8DZ_p_ZP3-8MA2ovgup3b22L5Bn4/edit#heading=h.zbg0nbu53vfv