Add candidateExpression extension

[fredhersch]

Is your feature request related to a problem? Please describe.
When populating a Questionnaire via the data capture library, I want to be able to provide answer options (this is different from setting the initial value) from resources that are related to the context (e.g. filling out a questionnaire based on a specific patient)

Describe the solution you'd like
SDC Library support for candidateExpression extension using FHIRPath - see specification

For example:

• For a given patient questionnaire, there could be a field asking who is the Next of Kin.
• For the answerOptions I want to pre-populate with any existing relatedPersons, but also allow text entry
• The list of relatedPersons would be set by the candidateExpression

See sample questionnaire for additional examples

Additional context
This is related to issue #965

[RaaziaTarique]

Extension: Candidate Answers Expression:
A FHIRPath or CQL expression, or FHIR Query that resolves to a list of candidate answers for the question 
item or that establishes context for a group item. 
The user may select from among the candidates to choose answers for the question.

Source: http://build.fhir.org/ig/HL7/sdc/StructureDefinition-sdc-questionnaire-candidateExpression.html

Basically candidate expression will provide a list of possible answers using either FHIRPath , CQL expression, or FHIR Query . SDK has support of FHIRPath and CQL . Do we need to add support of FHIR Query as well?
candidateExpression might contain repeats field which will make this ticket ( #726) a pre-requisite.

CC: @f-odhiambo @ekigamba

[f-odhiambo]

@fredhersch @jingtang10 @Tarun-Bhardwaj check the above comment from @RaaziaTarique

[pld]

Can you have the CQL or FHIRPath that makes up the candidateExpression use a value that was already entered in the Questionnaire (but has not yet been saved as a QuestionnaireResponse)?

If yes, then we can implement dynamic cascading selects with this, and we can close/this will cover the functionality requested in #979

[f-odhiambo]

From the above comments by @RaaziaTarique and @pld, this issue/solution can be covered in issue #1039 and thus close it. Kindly advise
CC @RaaziaTarique @pld @fredhersch @jingtang10 @RaaziaTarique

[Tarun-Bhardwaj]

From the above comments by @RaaziaTarique and @pld, this issue/solution can be covered in issue #1039 and thus close it. Kindly advise CC @RaaziaTarique @pld @fredhersch @jingtang10 @RaaziaTarique

@jingtang10 , could you please confirm if this issue can be closed basis that it will be addressed by #1039 ?

[pld]

#139 relies on something in draft, and also I do not think supported by the SDC, but even if it was do we feel ok relying on something in Draft stage?

Seems safer to work off of candidateExpression, which is in trial-use

[jingtang10]

A FHIRPath or CQL expression, or FHIR Query that resolves to a list of candidate answers for the question

Agreed here with @RaaziaTarique. I think in order to implement the example in http://build.fhir.org/ig/HL7/sdc/expressions.html#candidateExpression, we will need x fhir query support. I suggest we add a pacakge in fhir engine with an API that takes an xfhir query and return a list of fhir resources. Can we do this as a starting point?

@maimoonak explained the real life use case of this in open srp while answering a question of child immunization the health worker might need to search for the mother of a child to link their records. That could be done via candidate expression.

@fredhersch @f-odhiambo I think this ticket requires more effort than perhaps we expected.

[pld]

A couple other use cases:

• Assigning a healthcare worker to a patient, from the set of Practitioners attached to a specific CareTeam, Organization, and/or Location
• Assigning a CareTeam, Organization, or Location to a patient from the set of those resources

CC @Gental-Giant @AnnieMungai @dubdabasoduba if you want to add other dynamic select use cases

[KhumboLihonga]

Just found this discussion and thought I'd include some of our use cases as well:

• We need to be able to retrieve a list of community health workers working at the signed in user's facility, to assign to a patient.
• We need to be able to retrieve a list of patients to be used when assigning a guardian to a patient in the instance where the guardian is a patient themselves.
• We need to be able to retrieve a list of patients to be used when assigning a mother to a child.
• We need to be able to retrieve a list of locations to assign to a patient.

This extension is quite important for our project. For instance, as a workaround, we have tried to add all the locations (over 5000) as answerOptions to a choice widget but this is making the questionnaire too large and on some devices, the questionnaire fails to open at all and crashes the app.

[f-odhiambo]

FYI - a pre-req to this and completion of answer-expression is #1479. i.e. x-fhir-query support.
CC @jingtang10 @fredhersch @Tarun-Bhardwaj @KhumboLihonga

[f-odhiambo]

Waiting for answer expression work to be merged , as a pre-requirsite for this task to be implemented , has some reusable methods/funtions

[f-odhiambo]

There is an overlap between https://build.fhir.org/ig/HL7/sdc/expressions.html#answerExpression & https://build.fhir.org/ig/HL7/sdc/expressions.html#candidateExpression there is a minor difference but both have x-fhir-query and choice-column use which is already done 1039. Thus the two tickets are related but not similar

[KhumboLihonga]

@f-odhiambo from my understanding, answerExpression is based on other answers in the questionnaire (as per the example), while candidate expressions can be based on information outside of the questionnaire itself. For instance, getting a list of patients to assign as a guardian of another patient. Does this sound correct?

[f-odhiambo]

Update - This issue depends on #1480 being merged as it uses the choice column which is already done in 1480

[fredhersch]

@f-odhiambo any update on this issue? Is it being worked on currently?

[f-odhiambo]

This issue depends on PR #1480 being merged as it uses the choice column which is already done in PR #1480.
No WIP for this item at the moment CC @fredhersch

[maimoonak]

The candidate expression / details is a powerful extension that allows fetching data from database using x-fhir-query and using that to populate and control flow of information into various elements of questionnaire.

• answer-options -> just like answer-expression Support for answerExpression extension #1039 Answer expression extension implementation #1480 , it allows limiting user input to a set of choices. The difference is that asnwer-expression resolves to a list of permitted answers for a question item. While the candidate expressions is intended to be a suggestive set, not constraining. The user should be free to enter or look-up additional values. see answer-expression, candidate-expression and candidiate-expression example for details.

{
      "text": "Choose vaccinations administered",
      "type": "reference",....
      "extension": [{
          "url": "http://hl7...../StructureDefinition/sdc-questionnaire-answerExpression OR candidateExpression",
          "valueExpression": {
            "expression": "Task?code=33879002&status=ready&_sort=period", .....
          }
        }, {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-choiceColumn",.... }]
    }

AND

• populate dependent / child questions -> candidate-expressions can use a 'name' for one question which can lead to population of other dependent questions. i.e. the query of candidates of parent can be referenced by its 'name' in initialExpressions of child questions to populate the child answers. Details on population can be seen here
  • point 6 - For Choice Selection, use the sdc-questionnaire-candidateExpression to make available a list of possible answers. This should always be resolve to an item of appropriate type unless element has a type of Reference
• repeating groups -> the candidate expression as defined above can be used to generate repeating group dynamically provided that the candidate-expression is on a repeating group and each item derives its value/answer from parent group element ,candidate expression by name see example here. Details on repeating and population can be seen here can be seen here
  • candidateExpressions can appear on groups as well as questions. If they appear on a group item and the group item is allowed to repeat, then a separate group instance is created for each repetition. The variable named in the candidateExpression extension is set to the value of the candidate for use in continuous population of descendant items.
  • For example, a candidateExpression might resolve to a list of Conditions. After the user picks the relevant conditions, a separate group would be created for each and child items for the condition code, severity, onset date, etc. could automatically be populated using an initialExpression based on the variable name from the candidateExpression.
  • The questionnaire-choiceColumn extension can be used to control which data elements should be displayed
  • The repeats suggests that to constrain the minimum number of elements permitted for a repeating element minOccurs extension can be used. Similarly maxOccurs should be used to represent max elements... (and not mentioned in specs but if both have same value then it should be used to display fixed set of repeating groups with no add/remove button)
  • example summary below.

{
  "extension" : [{
      "url" : "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-candidateExpression",
      "valueExpression" : {
        "name" : "selectedContact", ....
        "expression" : "RelatedPerson?patient={{%patient.id}}&active=true"
      }
   }], ... ,
  "type" : "group",
  "repeats" : true,
  "item" : [{
      "extension" : [{
          "url" : "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-calculatedExpression",
          "valueExpression" : { "language" : "text/fhirpath",
            "expression" : "%selectedContact.name.first().select(text | given.first() & ' ' & family)"
          }
        }], ... 
      "text" : "Contact Name",
      "type" : "string",
      "repeats" : true
    }, {
      "extension" : [{
          "url" : "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-calculatedExpression",
          "valueExpression" : { "language" : "text/fhirpath",
            "expression" : "%selectedContact.telecom.where(system='phone').first().value"
          }
        }], ...
      "text" : "Contact Number",
      "repeats" : true
    }
]}

IMMUNIZATION REQUIREMENT
Considering all of the above our requirement is to

• create a form that allows us to select our multiselect Tasks for immunization using candidateExpression,
• then we need to ask if it needs to provide dates for each Task or all were performed on same date.
• if separate date for each Task a repeating group bound to candidateExpression should generate date input for each Task

A quick solution by fixing bugs, and adding cqf-expression functionality has been implemented into PR #1958 #1959 and #1960. A complete questionnaire after merging all PRs can be run into catalog. This is done by using enableWhen-expression, cqf-expression, and answer-expression for each vaccine. The expressions are used to control skip logic and question title to make it a little dynamic in nature but not completely dynamic and robust as candidate-expression allows .

@fredhersch @pld @dubdabasoduba @ekigamba @f-odhiambo @jingtang10 @owais-vd @omarismail94

[jingtang10]

thanks @maimoonak for an excellent write-up.

the distinction you pointed out between answer and candidate expressions is spot-on. answer expression is to limit choices, where candidate expression is to suggest some answers. It is, however, still possible that a question has both answer and candidate expressions, in that case the candidate expression should probably suggest answers in the set defined by the answer expression.

i see your point about population for child questions, but i don't see it as specific to candidate expression. you can populate child questions using expressions (perhaps define variables using variable expression?) without using candidate expression no?

finally, i want to add that due to the nature of candidate expression, i don't think it makes sense to support it in every type of widget... it probably makes sense to support it in auto complete, or open choice questions, but i can't see us supporting candidate expression in other choice types. additionally, supporting it in widgets like date/datetime would pose some UI challenges (how do you suggest a date in the date input?).

@maimoonak are there any mockups or examples of what you want candidate expressions to look like?

@shelaghm i expect we'll need some support here.

[jingtang10]

Discussed with @maimoonak:

I've approved Owais's PR - we'll merge it after the small comments are adressed, it'll be adding candidate expression extension to the questionnaire item.

We'll need possibly two follow-up PRs:

1. modify the questionnaire view model so that candidate expression's evaluation results are stored in memory and they should be associated with the repeated group
2. modify the fhir path hostin service so that when any expression is evaluated on the nested questions, the hosting service can help the fhir path engine resolve any references to the candidate expression by going up the tree of questionnaire response items.