Add max responses field to study

[becky-gilbert]

Addresses part of #1829 but should not close the issue.

This PR does the following:

• Changes to Study model:

  • Adds an optional max_responses field. Default is None.
  • Adds the helper property valid_response_count. For all study types, a valid response must:
    • not be a preview
    • be eligible
      And for internal studies, the response must also:
    • have a completed consent frame
    • be complete
    • not have rejected consent (only pending or accepted are counted)
  • Adds the helper property has_reached_max_responses. This returns True if the valid response count has reached/exceeded the limit, otherwise it returns False. If the study does not have are response limit, then this returns False.
  • Adds the stub method check_and_pause_if_at_max_responses to the Study model, which is called when a response object is saved/updated and the response is completed.

• Changes to Study create/edit form - see screenshots below:

  • Adds a "Set a response limit" checkbox question, which is unchecked by default.
  • Adds the max_responses field to the study create/edit form. This field is disabled by default, and becomes enabled if the "Set a response limit" checkbox is checked. Default is None.
  • If the study has a max_responses value, then the valid response count / limit is shown on the study details page, along with a progress bar (blue: up to 75%, yellow: 75-99%, green: >=100%). If the limit has been reached/exceeded, then "Response limit reached" appears below the progress bar.

• Adds tests for the new Study model properties valid_response_count and has_reached_max_responses.

To do (in separate PRs):

• Implement the check_and_pause_if_at_max_responses method.
• For external studies, call check_and_pause_if_at_max_responses when the response is first created.
• Changes to individual responses table

Screenshots for UI updates

"Set a response limit" checkbox (default: unchecked) and "Maximum responses" text box (default: none) on study create/edit pages, below the participant eligibility criteria section.

Valid response counts, response limits, and progress bars on the study details page.

[mekline]

Only comment is on handling the "too many respondents" cases - when we get extra people sneaking in the door, OR I guess if someone sets a max response level to under the current # of responses.

Thoughts:

• Not sure how important it is to distinguish 5/5 vs. 6/5 on the green bar, but it sort of feels weird to have no UI cue to that - ideas?

• Text on the max responses field - add a link to the (new) documentation page about how this works? Potentially also add note on extra participants, e.g.

• "The study will automatically pause when the number of valid responses reaches this limit. Note that participant sessions running when the limit is reached are permitted to continue. See [the documentation] for more information on response limits and tracking valid responses."

• Oh! Will the study automatically un pause if you un-validate a few responses, putting you back under the (overall or condition) limit? Probably it shouldn't, but make sure to model that user journey and make sure that that user doesn't feel stymied when they create some open slots and then want to re-open their study.

[becky-gilbert]

Text on the max responses field - add a link to the (new) documentation page about how this works? Potentially also add note on extra participants, e.g.
"The study will automatically pause when the number of valid responses reaches this limit. Note that participant sessions running when the limit is reached are permitted to continue. See [the documentation] for more information on response limits and tracking valid responses."

Yes, sounds great. I'll write up a draft of this in the docs so that I have a link to work with.

Not sure how important it is to distinguish 5/5 vs. 6/5 on the green bar, but it sort of feels weird to have no UI cue to that - ideas?

Agree, I'll think about it. Would a different color be too much? And/or I could update the text underneath the progress bar to "Response limit exceeded".

Oh! Will the study automatically un pause if you un-validate a few responses, putting you back under the (overall or condition) limit? Probably it shouldn't, but make sure to model that user journey and make sure that that user doesn't feel stymied when they create some open slots and then want to re-open their study.

I wasn't planning on automatically re-starting the study - just automatically pausing.

If the study is paused and then drops below the response limit because the researcher has un-validated some responses, then we could show a banner message at the top of the page (e.g. "The valid response count is below the limit for this study. Re-start the study if you want to collect more responses."). But I don't think we should automatically re-start the study for data collection without some kind of action by the researcher.

In the opposite case - if the study reaches the limit because the researcher marks some previously invalid responses as valid - then this WILL automatically pause the study, with a banner message at the top of the page (e.g. "Your study has reached the valid response limit and has been paused. If you want to collect more responses, increase the limit for this study, and then re-start it.").

Let me know if this sounds ok to you and if you have suggestions for wording. And we should definitely walk through these user stories to make sure everything feels clear and predictable.

[becky-gilbert]

Oh and the two scenarios above would occur on the Individual Responses page, when the researcher is changing the valid/invalid status of any responses. But I think the exact same things should happen on the Study Edit page if the researcher changes the 'max responses' value to be higher/lower than the current valid response count.

[becky-gilbert]

@mekline I just made the following changes to this PR - can you let me know what you think?

• Added help text under the `Maximum Responses' field on the study create/edit form. I'll fill in the link to the documentation once I have it.

• Updated the progress bar on the study details page to be red/striped if the limit has been exceeded.
• Added color to the "Response limit reached/exceeded" text, along with a note about the study being automatically paused.

The other things discussed above (related to automatic pausing behavior) are going in the next PR.

[becky-gilbert]

@mekline FYI, I've updated the valid response count so that, for internal studies, the response must have a consent frame, and consent must not be rejected.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
4 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud