Give direct feedback on why you cannot publish a form

[janagombitova]

Once Salim is done creating his survey form, he needs to publish it to move it from a draft state to a state ready for data collection. With every change he then makes to a published form, the form version updates and this version is not published. Only after Salim publishes it again are the changes he made visible on the app and webforms for data collection.

Publishing is an important task in the workflow of setting up a data collection and data collection cannot start without it.

But how publishing happens today, has many issues:

• Salim clicks to publish, the task runs in the background (so he can go do something else, plus it might take a while for longer forms) but there is no visual cue of it happening, and Salim needs to go to the messages tab to see if the publishing is completed.
• If Salim does not go to the messages tab, but clicks to publish and then makes a change again to the form, the form version does not update and things get messed up requiring him to reload Flow, try multiple times etc. So editing a form while is being published should not be allowed
• If the form is incomplete (dependency not fully set up, option question missing options, cascade missing resource, <-- all issues we prevent from happening but still possible if an old form is copied to be used now or if an option used in a dependency was deleted), publishing fails, but the user does not see an error message of it failing or the reason why it failed.

With this issue, we aim to handle the last problem: How might we make it clear to Salim that he cannot publish the form just yet, as the survey form is not complete.

The other problems listed above are here to paint the overall picture.

[janagombitova]

Why are we looking at this problem, if we eventually want to improve/refactor the survey editor? If we look at the support issues that come in, a large number is about survey forms not publishing. The support hero then needs to download the survey form, check the structure and point to the user where they need to make changes. This tasks takes up our time but also removes the independence from the user.

We aim to go from 31% of support requests to 5%. (total of 184, 30 were about publishing in Flow Reamaze channel in 2020 + 27 cases Jana received directly)

[Kiarii]

We could use a modal dialog aka pop-up to notify Salim that the publishing process cannot proceed given a failure in the requirements check - fill in the blank. In this case, the dashboard would not show the dialog about checking the messages tab for the form publishing status

To be explicit enough about why a form publishing fails, we need to list all requirement checks and their failure points - that way the info provided in the modal dialog can be direct

The modal cuts a few UX corners (but is the lowest hanging fruit [more like the fruit on the ground]):

• it assumes, one or a few failure points - it is not optimal for long (multiple) failure point communication
• it is out of context - once it is closed, Salim would have to 'publish' again to recall the failure points - this requires more cognitive effort on the part of Salim to keep the failure points in mind, and to traverse the form in search thereof.
• it cant take the user to the failure point

In form question validation (the higher fruit)

• In form requirement checks and question setting validation would have been ideal - given that if there are several failure points, a long modal dialog might not be of best use since Salim will forget some items once he has closed it and is back on the form editor.

• In form checks and validation might mean disabling saving or bounding a question in red when it is incomplete in any way (option naming, dependencies, and so on)

We need to consider the technical feasibility of in form validation for a number of reasons:

• We dont have to wait till Salim hits "publish" to run the checks, we can do this on a question basis when he attempts to Save
• It makes it easier to communicate a failed check in context, than listing a number of fails in a modal dialog
• (Bounding failed sections by red for instance would make it easier for Salim to spot sections requiring completion, if decide to do batch validation after Salim clicks "publish")

-- for future iterations: The publishing terminology would need realignment.

• A form should go from a 'draft' to 'published' via a 'publish' action, and back to 'draft' via 'unpublish/switch to draft'
• A published form cannot be 'published' again but can be 'updated'

[Kiarii]

reasons for failing to publish shared by @janagombitova

• dependency is not set up completely

the dependency check box is checked but no question selected the dependency check box is checked, question is selected but no options

• option question misses defined options

This was in the past - I doubt it still happens, but just to put it all down:

• questions miss question text (the actual question)

this is validated on the fly - you cant save if the question is blank

• ~question groups miss name~

• cascade resource not selected

It is actually possible to save an empty group name; not sure if publishing catches this though

[janagombitova]

In the call with the team today we decided the following:

• User workflow:
  • Clicks on Publish (that behaves in the same way - we do not change anything at this moment)
  • Sees a message that some questions are incomplete and needs to adjust them to be able to publish
  • The question groups holding these troubled questions are highlighted
  • Once Salim opens a highlighted question group, the relevant troubled questions are highlighted
  • If Salim makes a change to the question fixing what needs to be fixed and saves, the highlight is removed
  • Once the last question of the group is resolved, the highlight from the group is removed
  • If the form is ok, Salim can publish as before - click on the button - goes to messages to see if it is done
• From the above mentioned reasons why publishing can fail, we decided to start with a dependency validation.
• We will handle the other validations if we have time left
• Separate issues need to be created to ensure we can save a question or a question group only if all properties are well set, to prevent the reasons for publishing to fail to happen, but this is out of scope now
• We still need to have a way to highlight questions that are incomplete as an old form may be copied on which the validation before saving did not apply

[janagombitova]

Smaller issues to ensure that when Salim is editing a question, the question structure is complete and thus the form structure is complete reducing the cases of why publishing might fail:

• [x] Ensuring dependency is well set: https://github.com/akvo/akvo-flow/issues/3723
• [x] Ensure question group name is set before enabling to save
• [x] when deleting/changing an option on which another question is dependent
• [x] ~when deleting a question on which another question is dependent~ Already handled and not allowed by Flow
• [ ] when moving a question on which another question is dependent below the dependent question
• [ ] when deleting a question group which holds a question on which another is dependent
• [ ] when moving a question group which holds a question on which another is dependent below the group with the dependent question

[Kiarii]

Modal texts suggestion

Incomplete QG highlighting

Incomplete question highlighting

Respective error message, upon expanding an incomplete question

Highlight styling

Lets stick to the red used in Flow

[tangrammer]

In relation to https://github.com/akvo/akvo-flow/issues/3715#issuecomment-758864604

• Ensure question group name is set before enabling to save

@janagombitova does it means that it can't be equals to "New group - please change name"?

[janagombitova]

@tangrammer no. That is ok, not ideal of course, but still ok. It cannot be empty.

[janagombitova]

Yesterday evening I tested uat2, assuming what is merged is running there - version 20210119-100200.0d4c4112. My expectation was that once I create an incomplete form and hit publish, I will see the new pop up message and the group/question will get highlighted. That did not happen.

Secondly, my incomplete form got published. What is worrying me even more.

The form:

• Jana tests > Testing new publishing
• Incomplete question:
  • Group 2 - Depending on
  • Question 4 - Depending on d

Steps I took:

1. Created a form with 2 option questions and a few questions depending on them.
2. I tried deleting one of the option questions - this was not allowed by Flow, awesome.
3. I deleted one of the options from the other option question, knowing question 4 depends on it, option d. This question is now incomplete.
4. There is one more question that depended on option c and d, question 3. This one is ok.

@tangrammer and @muloem can you please check what might be going on?

[tangrammer]

@muloem @janagombitova this commit should fix option 3, https://github.com/akvo/akvo-flow/commit/5e12898d4fab853e3d04ce8a1bab4122390d15cd (i forgot to adapt this part) also added a check for group names here https://github.com/akvo/akvo-flow/commit/137af7a41ee69a6af41b96a9e1d51b6803c809b4

both commits part of this PR https://github.com/akvo/akvo-flow/pull/3734

[tangrammer]

@janagombitova BTW "I tried deleting one of the option questions - this was not allowed by Flow, awesome." not sure what will happen when we copied/worked-with old surveys 🤔 perhaps this flow constraint wasn't there at that flow history point

[janagombitova]

@janagombitova BTW "I tried deleting one of the option questions - this was not allowed by Flow, awesome." not sure what will happen when we copied/worked-with old surveys 🤔 perhaps this flow constraint wasn't there at that flow history point

@tangrammer no indeed, for copying cases we need to imagine the situation where a form, where we had no saving validation at all is being copied - so work with the most extreme in mind. However, my comment was more acknowledging my surprise that we had this validation in place today, I was not aware/forgot.

[janagombitova]

For now, we decided to handle checking dependencies. The other reasons why a form may be incomplete (missing options and text and group names) have not been addressed in this iteration. We decided to not add this as such cases are seldom. We will see how many more support requests we get with such cases before we decide to implement it as we rather invest the time in improving the survey editor and other more valuable tasks.

The validation works as expected! Good job!