Add eligibility to response model - fixes #1292

[becky-gilbert]

This PR adds a new 'eligibility' field to the Response model. The value is determined when the Response object is first created, and it is a list of one or more strings:

• Eligible
• Ineligible_TooYoung
• Ineligible_TooOld
• Ineligible_Criteria (based on the study's criteria expression)
• Ineligible_Participation (based on the study's must have/not have participated requirements)

The eligibility value will only be set for newly-created Response objects. Existing responses will have an eligibility field that contains an empty list.

The 'eligibility' field value roughly corresponds to the 'red text' warnings displayed under the "Participate/Preview Now" button, which let the participant know that the selected child is too young/old or does not meet the study criteria. However, there are some minor differences between these:

• If a child is too old for a study, then they are only shown the 'too old' warning text (even if they are also ineligible based on criteria/participation).
• A child is shown the same warning when they are ineligible based on the study criteria expression and/or the prior participation requirements.

Examples

Eligible

Participation page:

Data:

Study Responses -> Individual Responses -> Response details:

Ineligible: too young

Participation page:

Data:

Study Responses -> Individual Responses -> Response details:

Ineligible: too old

Ineligible: criteria

Participation page:

Data:

Study Responses -> Individual Responses -> Response details:

Ineligible: multiple reasons

Participation page:

Data:

Study Responses -> Individual Responses -> Response details:

Existing responses

The 'eligibility' column will be present but will contain an empty list.

[becky-gilbert]

Questions about this issue: what should the value of the eligibility field be in these cases?:

1. Child's birthday is missing, which means we can't calculate age range eligibility. At the moment, the eligibility value is blank for existing responses in the database. Does it also make sense to use a blank value when the child's birthday is missing? Or do we need another 'Ineligible'-type category?

2. Study's criteria expression is invalid (parsing error). Should we default to always treating the criteria check as eligible (since otherwise there will be no eligible children for the study)? Or always code this as 'Ineligible_Criteria'?

BTW, these issues revealed themselves in testing because (a) we don't require the birthday field in the Child account model, and (b) the criteria_expression in the Study model doesn't default to an empty string. So if it so happens that we did want to change those things, that might remove the need for handling these cases (except that maybe the researcher can still enter an invalid criteria expression - I'm not sure if there's any validation on that before it's saved).

[okaycj]

• Child's birthday is missing, which means we can't calculate age range eligibility. At the moment, the eligibility value is blank for existing responses in the database. Does it also make sense to use a blank value when the child's birthday is missing? Or do we need another 'Ineligible'-type category?

There's an issue on this #1285. If you look through the production database, all children have a birthday. This require for a birthday was enforced at the form level and probably should be at the database level. Assuming, we want to require a child to have a birthday.

• Study's criteria expression is invalid (parsing error). Should we default to always treating the criteria check as eligible (since otherwise there will be no eligible children for the study)? Or always code this as 'Ineligible_Criteria'?

It my preference to not have an invalid criteria. Can we do a better job of validating the criteria on form submission? For existing invalid criteria, could we signal the researcher in someway? Maybe on the preview child selection view?

[okaycj]

This is just a draft, but it seems to make sense. I'll do another review when you're ready.

[okaycj]

TextChoices! I should've known about this, very nice.

[becky-gilbert]

It turns out that we do require a birthday on the Child create form, and we validate the criteria expression on the study create/edit form.

I've updated the Child model so that blank is false and null is false. This ensures that a Child instance cannot be saved to the database without a birthday, which means that we don't need to validate the data that's coming out of the database (i.e. checking that a Child has a birthday before trying to access that field).

Similarly, I've added a default blank ('') value to the Study model's criteria_expression field. This prevents our testing tools from generating random text strings in this field when we create a new Study instance where the criteria_expression is not specified.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
2 Code Smells

No Coverage information
0.0% Duplication

[mekline]

Couple of comments from Ian on typos, but I think they are in the PR text rather than the codebase:

I found a few quick typos:
-"Eligibile" string should be "Eligible". Looking at the code examples in the comments, the actual code probably doesn't have this error and it's just in this documentation.

• "If a child is shown the same warning when they are ineligible based on the study criteria expression and/or the prior participation requirements." should remove the "If" at the beginning I believe.

[becky-gilbert]

Thanks Melissa and Ian! I checked the codebase and these errors are just in the PR text. Fixed! 👍

[okaycj]

LGTM! That was a lot of work.