Apply data approval workflow step to data points - MVP - estimated 39

[janagombitova]

For all the background information on this feature and the decisions around the MVP please check: akvo/akvo-product-design#82

Details (draft) The workflow will be applied on the data point level thus when viewing the list of data points in the Monitoring tab we have added the column Data approval, which shows the current workflow status of a data point. Here is also the place where the user can change the status (see mockups for both types, ordered and unordered).

• add in page pop up which enables to view workflow steps, to change and to save workflow step in the table (taking into consideration that the user has to have the permission to do so)
• save the time stamp and user name of who made the change of workflow status and show it
• change workflow status based on what the user applied

[janagombitova]

From planning poker meeting: Needs to be better defined (in more detail) and potentially broken down into smaller chunks. Questions like: What happens if a submission is disapproved on the 3rd step, is the 2nd one opened again? need to be answered.

[janagombitova]

Based on the discussion we had during the planning poker meeting, here are the mockups I could find and the ideas and understanding I have. Let's discuss this further once we reach to this issue.

Changing a workflow status for a data point

We are working with the analogy that data approval works as if the submitted forms move from one desk to another where they get checked and approved/disapproved by a particular person.

We have two types of data approval workflows:

• unordered - the sequence of the desks is not pre-set
• ordered - steps happen in a specific order and you cannot skip from one desk to a third one

In order to see which submission (data point) is in which stage/step of the data approval workflow we mark the datapoint with a status. The status is derived from the workflow step and the action the user took.

Unordered workflow:

Changing step on data point for an un-ordered workflow

• the order for un-ordered workflows is not important - datapoint can move from desk A to B, then to F and to A again. When creating the un-ordered workflow the user does not define the sequence and only the existing steps and the 1st step as the default one.
• this means that un-ordered workflows have only one status = same as the name of the step
• the status indicates that the data point is currently in that step/stage of the workflow

How does the data point status change with the approval steps?

Surveys that have a workflow added to them will also have an extra column in the data preview (as well as in reports) which will show the current status of the data point. The status is based on the approval given (or not given) to a data point.

Unordered workflow

• for an unordered workflow the status change is straightforward
• if there are 6 possible levels in the approval workflow, and the user selects 'level 3' to indicate that the point is OK for that level (or exists now in this level)
  • the patient in the hospital analogy: the patient goes for a scan and this stage in her treatment is marked in her folder
  • if she is brought in for surgery - this is also marked in the folder
• the Flow user sees his data points in the Monitoring tab and the newly submitted points have the 1st (default) status added to them
• he opens a point > sees a dropdown with all the created steps > and selects the step appropriate for the point

Ordered workflow:

Changing step on data point for an ordered workflow

• the order of steps is defined when the user creates the approval workflow
• ordered steps can have 3 statuses: 'Pending', 'Approved', 'Rejected' (or 'Disapproved')
• a new data point by default gets into the 1st step with the status 'pending'
• 'Pending' - means that the data point is in the workflow step, but the work is not finalized, thus the step in not marked as 'approved' and the datapoint remains in this step. 'Pending' means being in a current workflow step/stage.
• 'Approved' - once the point is given the status 'approved' for a workflow step, the work for this step in done and the point moves to the following step in the workflow and gets by default the status 'pending'. 'Approved' means moving forward in the workflow.
• 'Rejected' (or 'Disapproved') - once the point is marked in a workflow step as 'rejected' the workflow comes to an end and no more movement to the following steps is enabled. 'Rejected' means the workflow came to a halt and actions need to be taken on the lower steps.
• the user opens a data point and next to the current status (if he has the proper rights) he can open a dropdown with the 3 possible statuses for that stage of the workflow

How does the data point status change with the approval steps?

Surveys that have a workflow added to them will also have an extra column in the data preview (as well as in reports) which will show the current status of the data point. The status is based on the approval given (or not given) to a data point.

Ordered approval workflow Example case: data approval holding 5 steps and each step has a different user responsible

• data point is submitted and by default gets the status: 'step 1 - pending'
• user 1 deliberately selects pending > point status: 'step 1 - pending' + history log - timestamp - user 1 - step 1 - pending - comment
• user 1 approves step 1 > point status: 'step 2 - pending' + history log with timestamap - user 1 - step 1 - approved - comment
• user 1 disapproves step 1 > point status: 'step 1 - disapproved' + history log with timestamp - user 1 - step 1 - disapproved - comment
• user 3 opens point that was approved by user 2 in step 2 and now has the status 'step 3 - pending'
• user 3 approves step 3 > point status: 'step 4 - pending' + history log with timestamp - user 3 - step 3 - approved - comment
• user 3 disapproves step 3 > point status: 'step 2 - pending' + history log with timestamp - user 3 - step 3 - disapproved - comment
• user 5 opens point that was approved by user 4 in step 4 and how has the status 'step - 5 pending' user 5 approves step 5 (last step) > point status: 'step 5 - approved' + history log with timestamp - user 5 - step 5 - approved - comment
• user 5 disapproves step 5 > point status: 'step 4 - pending' + history log with timestamp - user 5 - step 5 - disapproved - comment

@muloem and @joycarpediem What do you think? Let's discuss this once we get to this point in the build

[janagombitova]

Test plan

You will need all three surveys that you have assigned data groups to to have data points with data.

For Ordered approval groups with no user limitation

1. Go to the Data tab and Monitoring subtab
2. Open the survey that has an approval group assigned to it, but NO responsible users and click to find data
3. Data points are shown in the list. In the new column Approval status all points have the 1st step and status 'pending'
4. Any user (your current user, all your test users) can change the points approval status
5. Click on the 1st points approval status > a window shows with all the possible steps. The 1st step shows the dropdown with the 3 statuses: Pending, Approved, Rejected; comment box; and Submit button
6. Change the status of this point to Approved, write a short comment and hit submit
7. For the 1st step you now see status Approved, with the timestamp, your user name and comment. The 2nd step is now open, status is Pending, you see the dropdown, comment box and submit button. Close the window
8. Open the 2nd data point and change the status to "Pending". The 1st step is still open, but a history log is shown with status pending, timestamp, user name, no comment as you did not add any.
9. Open 3rd data point and change status to "Rejected" and add a comment. the 1st step is still open, but a history log is shown.
10. Open 4th data point and change status to "Approved" on the 1st step and also "Approved" on 2nd step. The 3rd step is not open and in "pending"
11. Open 5th data point and change status to "Approved" on the 1st step and "Rejected" on the 2nd step. A history log is shown on the 2nd step and it remains open. The 3rd step is not opened yet.
12. All 5 data points have now an updated Approval status.

For ordered approval groups with user limitations

(You are logged in user was assigned to step 2)

1. In Monitoring subtab of the Data tab select your survey that has an ordered approval group and responsible users per steps assigned to it
2. The data points are shown on the list of points and for the Approval status they all have 1st step - pending
3. Open a data point, you cannot make any changes - you do not see the dropdown, comment box or submit for the 1st or any steps, not even step 2 that you are responsible for.
4. Log out of the dashboard and log in with the test user account who is responsible for step 1
5. Select the survey in the Monitoring tab again.
6. Open a data point, you should now be able to change the point status for step 1
7. For the 1st data point make the status approved and add a comment > the status change, timestamp and user name are logged down. The 2nd step is now in status 'pending' but there is no submit not comment box for you open to change it.
8. For the 2nd data point change the status to 'pending'. Change is logged down, and the 1st step is still open while the 2nd step is still closed for editing
9. For the 3rd data point change the status to 'rejected'. Change is logged down and the 1st step is still open while the 2nd step remains closed
10. Log out of the dashboard and log in with the test user who is responsible for the 2nd step of the approval group.
11. Select the survey in the monitored tab and you should see the changed statuses for the 3 data points.
12. Open the point where the status is now in the 2nd step - pending. You cannot make any changes to the 1st step but only to the 2nd step. Approve the 2nd step. Now the status is in the 3rd step - pending, but you cannot edit it.
13. Open the point where the status is in the 1st step - pending. You cannot make changes to the step.
14. Open the point where the status is in the 1st step - rejected. You cannot make changes to the step.

For unordered approval groups with no user limitations

1. In the Monitoring subtab of the Data tab, select the survey where you have an unordered approval group with no users assigned to it.
2. Data points are shown in the list and the approval status is the default status (1st step in the approval group).
3. Open the 1st data points approval status > you see a dropdown with all steps for this approval group, a comment box and a submit button.
4. Select one step from the dropdown, write a comment and hit submit. The status is now logged down with the step name, time stamp, your name and comment you added.
5. Repeat 4. twice. You should be able with all attempts to choose from all steps in the list regardless if they were selected before or not and each submission is logged down with the latests on the top of the list.
6. Change the status of 2 more data points. Make sure each of the three points has a different status in the end.

For unordered approval groups with user limitations

1. In the Monitoring subtab of the Data tab, select the survey where you have an unordered approval group with users per steps assigned to it.
2. Data points are shown in the list and the approval status is the default status (1st step in the approval group).
3. Open the 1st data points approval status > you see a dropdown with only the steps you are responsible for, a comment box and a submit button.
4. Select is from the dropdown, write a comment and hit submit. The status is now logged down with the step name, time stamp, your name and comment you added.
5. Repeat once more. You can only, with all attempts, choose from the steps you are responsible for in the list regardless if they were selected before or not and each submission is logged down with the latests on the top of the list.
6. Change the status of 2 more data points.

Repeat the test plan in different browsers

[janagombitova]

Notes from testing

• in the list of points on the Monitoring tab the order or points is NaN >> either there should be no numbering or the order numbers should show the point count

For Ordered approval groups with no user limitation

• order of steps is changed and does not reflect the order of steps as created by the user (see https://github.com/akvo/akvo-flow/issues/1659#issuecomment-250172118)
• approval status in the column should show: step name - approved/pending/rejected. It now only shows the step name
• the 1st step is Step D and I changes to Step D - APPROVED > the following step should now be Step C - Pending but in the list of data points the point still shows Step D. It should show Step C - PENDING
• I submitted the point status Step D - Pending > the Step D is now closed for editing and I have the following step open. I should still have Step D open, because I did not approve it yet, and Step C (the following one should still be closed) >> the expected change is:
  • if user submits APPROVED: the step closes and the following one is opened for submittion
  • if user submits PENDING: the step remains open, the following step is still closed and changes can only be made on the 1st step
  • is user submits REJECTED: the step is closed and the following step is not opened

For Un-ordered approval groups with no user limitation

• the UI is a bit different for unordered approval groups >> the steps do not have pending, approved and rejected but the steps themselves act as the statuses >> so there should only be a dropdown with the steps and the user selects the current step and adds a comment

• so you should see the dropdown with the created unordered steps + text box and submit and below the list of steps submitted per that point before

@muloem that is all so far - will add more in an hour or need. Need to relocate now

[janagombitova]

@muloem I would propose to ease up the plan and looking at the time - we can also perhaps 1st make sure ordered group work fine and leave unordered for the 2nd sprint

[janagombitova]

Hey @muloem,

I found another odd thing:

• I assigned a approval group to a survey and opened Monitoring
• The step I can start approval is the last one even though I have not done this before with this group on this survey
• I cannot open the other steps even though I have no users assigned here yet

[janagombitova]

Notes from 2nd round of testing

Ordered group

Default step ordered group

• when opening a new survey in Monitorign tab which was not worked on yet the default step shown is not the 1st one in the list
• also when I approve the step it moves oddly - not in order

If step is approved the following step is opened and shown in data point overview

• works good now - fixed
• but because the approval began on step 2 and not step 1 it moved forward not it the good order

Submitting a pending status

• when submitting an approved status, there is a history log of the status, my name and time
• this does not happen if I submit pending

Rejected

• if submitting rejected it should not open the following step - that works well
• I think we need to re-evaluate the behaviour based on user feedback, for now we can keep the rule - if rejected - full workflow is closed if you @muloem agree

Unordered group

• creating a separate issue to handle the execution of un-ordered groups as the interaction is different and suggest we deal with this one after the first release
• https://github.com/akvo/akvo-flow/issues/1777

[janagombitova]

@muloem here is the test I have run just now and I am not sure if what you shared is fixed or not, but I could still not submit a 'pending' status with a comment and did not get it logged down in the history. So what I am expecting with pending is:

Case 1:

• I select approved on step 1 > submit > approved is saved in history log
• step 2 is open by default in pending

Case 2:

• I have pending by default in the dropdown > I leave pending, type in a comment and submit
• I get a history log of the pending submission
• the step is still opened with pending in the dropdown and I can submit another pending, or approve or reject

[muloem]

@janagombitova ok noted. it should be sorted out now.

Also I just realised that perhaps comments will probably be over our usual 500xter limit. Should we impose the limit or store whatever they push in? It also means that @loicsans will have to adjust UI a bit to wrap the comment text.

[janagombitova]

@muloem and @loicsans I think 500 characters is quite a lot of text to write as a comment and think it should suffice for now, but that is just my personal feeling. What do you think?

@muloem Thanks. I am ready when you are

[janagombitova]

Notes from 3rd round of testing

(have tested only ordered group using survey: 1.9.11 UAT Folder - testing data approval > Jana tests > Tuesday test 1 (only testing ordered groups))

Homework from previous rounds: All done 👍

• Default step ordered group - order of steps shown good from the start - DONE
• Approving not happening in correct order - works as expected - DONE

New notes

tested editing an approval group in use 👍

• if the user adds extra steps to an approval group - works perfectly fine regardless the last status all rules are respected
• if the user renames an existing step (in my case the first step - went from "one" to "yellow) - works perfectly as well
• if the user removes a step (in my case I removed step "two") - the step is removed from everywhen - works fine
  • here I would suggest to first cross check if the approval group is used on data
  • if not then ask the user if he really wants to delete the step
  • if used with data > need to create the sam UX pattern as we have with questions in a survey maybe - to be discussed and figured out later

testing adding more data 👍

• works perfectly fine

Pending (based on user feedback) - https://github.com/akvo/akvo-flow/issues/1778

• the pending works better now than before - so we have an improvement already, but we will still lose the track record of someone submitting a pending issues once the step is approved.
• I do not think this is an issue and my comment is only based on my hypothesis that the manager will want to have a full track record of everything
• I would suggest to leave the implementation as it is now, create a separate issue for this and see if in the 1st round of user testing SNV will give us such feedback or not (validate the hypothesis with real users)

Cannot close window if all steps are approved

• I have approved all the steps for one data point and cannot close the window where I was approving
• the status indication (clickable link) is not show anymore << I would click on that to close the preview
• I assume it is gone because there is no more step to go to, to be in the following pending status - so I suggest if the approval group is done, we leave the last step as the status indication

• once I reload the data point list, I see that those points do not show the status indication and I cannot open them either - so I think that something is wrong and not that they have passed the full approval process

• if the last step is Rejected then the status remains on the last step, this would be good for approved lasts steps as well. The user can then check himself if the last step is approved or rejected by clicking on the status for the point

Full page refresh

• After refreshing the full page, I opened the monitoring tab again and opened my survey I was just working on
• in the list of points all statuses indicated in the column were shown as 'one' (the 1st step)
• but after clicking on each point, as I was worried I lost all the approvals I have done - the statuses showed the proper step > so after opening a point one by one the status for that point was shown properly again

[janagombitova]

Test plan

for testing this issue on UAT please see test plan above https://github.com/akvo/akvo-flow/issues/1664#issuecomment-249536207

[janagombitova]

Notes from testing

All issue that relate to this test plan but will be handled separately:

• handling unordered groups https://github.com/akvo/akvo-flow/issues/1777
• pending status changing https://github.com/akvo/akvo-flow/issues/1778
• cannot close window if all are approved https://github.com/akvo/akvo-flow/issues/1785
• status not shown after full page refresh https://github.com/akvo/akvo-flow/issues/1786
• respecting responsible users https://github.com/akvo/akvo-flow/issues/1774

For the remaining workflow the implementation passes the test plan 👍