[Design Issue] "APD Editing Limited to One User" Dashboard Experience (Multi User Support)

[jeromeleecms]

As we look to support an expanded user base with MMIS IAPD, V1, an APD author should not be able to edit an APD that is currently being edited by another user.

This presents itself in two potential cases:

1. APD user is on the dashboard and wants to access an APD that is currently being edited
2. APD user attempts to directly access an APD from their browser using an old link

The Dashboard will need to be updated to show

1. Editing status of an APD
2. Who is the current editor/Who was the last editor
3. The dashboard updates when the user when the APD is no longer being edited
4. Users can download a PDF preview no matter the status of the APD
5. The next step of multi user support will be how to notify users that new APDs were updated, so the dashboard update should reflect that

Some things to discuss:

1. What triggers a release of an APD for editing
2. How do we inform users that the APD can not be edited at this moment based on the two cases above

This task is done when…

• Dashboards Design reflect the editing status of an APD
• Dashboard Designs reflect the experience when a user can not edit an APD
• Dashboard Design allows user to download a PDF preview
• 508 visual, content, and UX considerations and/or recommendations are reviewed
• designs are shared
• designs are approved by product
• if there is a long discussion, a summary of changes for dev will be added to the last comment before transfer
• a list of changes to be made if this is improving an existing feature

---

Test Cases for #4016:

Given	When	Then
a user tries to access an APD via the APD dashboard or direct link	that APD is currently being edited	a modal should appear informing the user that the APD is locked from editing, modal should also have a button to bring you back to the APD dashboard
a user is on the APD dashboard	another user enters an APD	the dashboard should show that the APD is currently being edited, it should have the "Locked from Editing" status and should be locked. (need to manually reload the page for dashboard updates until websockets have been implemented
a user is on the APD dashboard	a user that is editing an APD exits the APD or logs out	the dashboard should show that the APD is no longer being edited, the "Locked from Editing" status should disappear, and it should get unlocked (need to manually reload the page for dashboard updates until websockets have been implemented)
an unlocked APD	a user enters that APD	Once accessed, it should immediately save. This is how we are going to lock an APD when a user starts editing it
an unlocked APD	two users access that APD same time	one user is kicked off (?)

Test Cases for #3919:

Given	When	Then
a user is on the APD dashboard	an APD is currently being edited	That APD should have the "Locked from Editing" status
a user is on the APD dashboard	an APD is currently being edited	That APD should show the current user editing that APD
a user is on the APD dashboard	an edit is made to an APD	That APD should show the user that made the change(?), and the time and date of the change (must manually reload the page for dashboard updates until websockets have been implemented)

Test Cases for #3917:

Given	When	Then
a user is on the APD dashboard	a APD is locked or unlocked	Should be able to download a PDF preview of the APD

[akuas]

@beparticular @jeromeleecms Can you please review this ticket? I will write up a summary of this work once we agree it is ready to move to dev
https://www.figma.com/file/6eVvo7JjvXiovGTR4BoVgK/CMS-eAPD-2022?node-id=8691%3A27284

[jeromeleecms]

1. For the Dev team, does the "Read Only Preview" need to go away until we get that in place?
2. For the Accessing an APD using an old link: Can we update the modal text to align with the text from "Accessing an APD that has been locked from editing from the dashboard?" In the note, do we need to indicate that this modal only applies to "Active" (or non deleted APDs)? The delete APD error message from an old link should take precedence over this.
3. When the APD has been released, the Last Edit by last editing by / time stamp / version should update if needed, correct?
4. Do we need to mockup a version where a user is on the dashboard and then the state moves to "APD has been locked from editing."

[akuas]

@jeromeleecms Thanks, I will make those changes. @thetif Jerome had a question about the read only preview ^

[akuas]

@jeromeleecms We dont need to indicate active links because being able to access a deleted APD is a bug

[jeromeleecms]

@akuas 👍 wasn't clear if there was an order of operations when opening a deleted link.

[akuas]

@jeromeleecms Not yet, I believe. We still have to figure that part out

[beparticular]

Progress: this issue is well documented here and in Figma as our ideal state for multi-user editing.
We won't be moving this into dev for some time, and our MVP is done in ticket #3918 (and the corresponding dev ticket), so we'll add this back to the design backlog for re-evaluation at the right time, to make sure this all still works according to the information we have in the future.

I also moved the first batch of test cases above into dev ticket #4105
The remaining test cases will still be part of the dev tickets that come from this ticket later in 2022.
https://www.figma.com/file/6eVvo7JjvXiovGTR4BoVgK/CMS-eAPD-2022?node-id=8800%3A27221

[akuas]

Below is the previous designs done 6.2022. I will be building upon this on the mmis file.
https://www.figma.com/file/6eVvo7JjvXiovGTR4BoVgK/CMS-eAPD-2022?node-id=10526%3A29085&t=7382d8Zpza6zIJKL-1

[akuas]

Decision As of March 22 2023: Proceed with Option 1

Single user access lock. I am presenting two options for consideration.
https://www.figma.com/file/hJpKHKU6fz5J0Z7fisSwa2/eAPD-MMIS-2022?node-id=4945%3A20992&t=6kIZrWmPvVqzjxNX-1

Option 1: Modal Expands

1. For the 1st option, user sees a tag that says the APD is locked for editing. As a fail safe, they can also click on the APD and receive confirmation on why the APD is locked and their next possible action.
2. The pros of this design is this flow of clicking the APD and receiving a modal is the exact workflow for the lock and submit. In the lock and submit workflow, if a state admin locks the APD, state authors cannot access the builder unless the APD is unlocked. In that way, the experience of locking in the lock and submit and locking for single user access is the same, but just a different reason.

Option 2: Tooltip provides context, APD disabled

1. In this design the APD link becomes disabled if another user is accessing that APD and the link and there is a lock symbol indicating that it is temporary locked for editing. You can expand the carrot to get more context on why it is locked. Once an APD is released, the APD reverts back to its usual status. @SGilliamA1M We had talked about having a notification when an APD is released and available to edit but I decided not to do that because it wouldn't make sense to have that status (i.e. open to edit) for 1 APD and not the rest, we don't currently have the functionality to notify users so they would have to stay on the dashboard to find out, and 4016 is a temporary solution to APD entry overrides, once we allow multi-user access this design will be obsolete.
2. Pros of this design : It can be easily removed once we allow multi-user access and it does not involve the user clicking on a modal first.

With that being said @jeromeleecms @stephanieboydcms @SGilliamA1M which option do you prefer?

[SGilliamA1M]

Thanks @akuas! I reviewed the two options you proposed and prefer Option 2. I also added some feedback to the Figma file. Please let me know if you have any further questions. Thx!

[stephanieboydcms]

Thank you @akuas, I prefer Option 2 with one minor suggestion!

[akuas]

Parking Lot : 3.23.2023

1. 4016 MVP: Just add the locked component, need to identify if it is locked, that users cannot click on the APD, and the ability to download the latest version
2. Download link opens up the print window
3. We can give the context behind why they multiple users cant access an APD at the same time in the information alert
4. Make information alert dismissible
5. Remove versioning and will need to talk to Tif on whether Last edited by can be easily implemented, if not remove

[akuas]

@mirano-darren Do you mind looking at this and letting me know if there are any questions you have in regards to use cases. You created test cases for the previous design and I want to make sure I have all my bases covered for this iteration. Also, please let me know if you have questions about the design here. There are you use cases, user 2 goes to the dashboard and sees that an APD is in use and when a user uses an old link to access an APD.
https://www.figma.com/file/hJpKHKU6fz5J0Z7fisSwa2/eAPD-MMIS-2022?node-id=4945%3A20992&t=W5U5XJOZ7CbQto7E-1

[akuas]

@thetif Hi Tif, do you mind looking at these designs and letting me know what you think, are there any technical considerations I need to consider with this design?
https://www.figma.com/file/hJpKHKU6fz5J0Z7fisSwa2/eAPD-MMIS-2022?node-id=4945%3A20992&t=W5U5XJOZ7CbQto7E-1

https://www.figma.com/file/hJpKHKU6fz5J0Z7fisSwa2/eAPD-MMIS-2022?node-id=4948%3A21306&t=W5U5XJOZ7CbQto7E-1

I do have some questions for you though.

1. Can we implement download APD from the dashboard now? I wanted users to have a secondary action if an APD is in user by another user. Is it the same process as the Export button on the export and submit page
2. Can we personalize alerts by adding a user's name?
3. Do you think we need to block users from opening multiple APD links at once?

If you have questions about the design, please comment here or I can explain further in parking lot.

[akuas]

Notes: As of March 29 2023

No longer up to date but keeping it for posterity.
This view shows the single user APD access, where if one user is editing an APD, noone can edit the APD until the 1st user release the APD by navigating out of the APD or signing out( ession timeout or manually)

Single User Access Workflow

1. You open the dashboard, see the status “Temporarily locked for editing.” As a fail safe, if users don’t see that they click on the APD, it triggers a warning alert below the APD name and FFY, giving more detail and direction. In the same action, the APD link becomes disabled. Instead of disabling from the jump, it instructs users as to why it is disabled. Users can dismiss the alert by clicking the x symbol and or download the latest version of the APD with the download APD button.

When is an APD released

1. An APD is released/available to edit when:
   User 1(the person in the APD) exists out of the APD in any way i.e. log out, session timeout, navigate out of APD through top and bottom nav, navigate to a different APD

Fontawesome Icons

1. rectangle-xmark for the alert
2. lock symbol
3. lightbulb-on (It is a pro icon, so I couldn’t download it, so I drew it on figma. But I want to know if the dev team has access to it.)
4. clock symbol
5. trash symbol

Overall Design Additions

1. Add the full name of MMIS and HITECH to the section labels
2. Just have the ffy shown as a tag instead of MMIS IAPD|FFY 2022-2023
3. Add icons to certain details on the dashboard: temporarily locked for edited, last edited, created and delete
4. Make the delete button red to flag that it is a destructive action
5. Present an alert conditionally when users click on a locked APD. Remove alert when an APD is released or when the user manually dismisses APD.

If you click on the Download APd button, it opens a browser dialog to print or save.
It opens the latest version of the APD so it should open the same version as when you click on the Export button in the Review and Export page.

[mirano-darren]

This is looking great! Couple of use cases that came to mind:

1. Should we also disable deleting an APD if it's locked from editing?
2. Is it possible to have multiple of these modals open? or does it close the other modal when a new one is opened
   
3. What should the empty state look like? as in what if there is no APDs?
4. Is the time zone always going to be EDT?
5. Still unsure how unlocking works. Say user 2 is waiting on the dashboard and user 1 leaves the APD. Is user 2 expected to refresh the page to be able to access the APD?
6. What if the APD name gets updated within the APD? Is the dashboard expected to update in real time? or on reload? same question for the FFYs
7. This is a very very specific scenario, but what if two users access an unlocked APD at the same time?
8. What happened to the direct link conversation? I could see users potentially bookmarking the APD overview (or any page for that matter) which would give them a direct link to the APD. What If it's being edited then?

[thetif]

Answers to your questions

1. Can we implement download APD from the dashboard now? I wanted users to have a secondary action if an APD is in user by another user. Is it the same process as the Export button on the export and submit page
   not yet because we haven't implemented the custom PDF, until we do that we are limited by having to display all of the data going into the PDF and then printing it
2. Can we personalize alerts by adding a user's name?
   yes, that is doable
3. Do you think we need to block users from opening multiple APD links at once?
   I think we might have to lock multiple APDs at once

Some questions I had:

1. Could we change Last edited: to Locked: with the timestamp that it was locked?
   
2. If the APD is locked, could we remove the link? Or if not and they click the link, could we bring up the modal on the dashboard page? It's going to be more complicated to actually open the APD and show the error message.
3. Is that warning a modal or an alert that is displayed inline?
4. I'm not sure if we should let them print while a user has the APD locked because the data is in flux. Once we have custom PDFs aren are saving versions, we will be able to let them download the latest one that was saved before it was locked

[akuas]

1. Thats a good point, I will make the delete button disabled when it is locked from editing
2. Yes, it is possible to have multiple alerts open if you click on a locked APD. I doesn't behave like the modals in the previous design because you can interact with other things on the page and choose not to dismiss it.
3. • I will answer how the dashboard would look like in an empty state in a bit.
4. The time zone will be localized, so AK will have a AKDT time zone.
5. I am expecting the dashboard to auto-updating so when user 1 leaves the dashboard will automatically update to remove the status Temporarily locked for editing and the alert. Do you see any technical issues with this method?
6. If the APD name of FFY is changed I expect the dashboard to be updated in realtime.
7. This is a very very specific scenario, but what if two users access an unlocked APD at the same time? Im not sure :(
8. For the direct link workflow, we will use the previous design with the modal.If users bookmark the APD overview, the page will quickly transition from the regular APD overview to a modal overlay that says you have to go to the dashboard.
   https://www.figma.com/file/hJpKHKU6fz5J0Z7fisSwa2/eAPD-MMIS-2022?node-id=4948%3A21306&t=GhyTXWSdoDKf3HPt-1

[mirano-darren]

will defer to @thetif for the question in 5 :)

[akuas]

@thetif Thanks for the answers.

1. I changed last edited to locked but why this change? Is the date not being updated when another user is accessing the APD?
2. Im not sure if we are thinking the same thing but clicking on the APD triggers an alert; it doesn't actually open the APD. Is that what you were referring to as complicated. I would be fine with using the modal instead, but I would need Jerome's feedback and some more context behind that at Design Sync.
3. It is warning alert that appears inline of each APD that is locked.
4. Okay, that is fine, I have removed the download APD button and they would not be able to access the Export and Submit page anyway to print an APD.

[akuas]

Closing Notes: As of March 30 2023

This view shows the single user APD access, where if one user is editing an APD, no one can edit the APD until the 1st user release the APD by navigating out of the APD or signing out( session timeout or manually)

Use Case 1: Single User Access Workflow from the Dashboard

1. User 1 accesses an APD first, causing an APD to be locked for editing for User 2 and other users, until an APD is released.
2. User 2 will see a fade in and fade out yellow background color pointing out which APD has recently been locked.
3. When an APD is locked, the APD link will be disabled, the delete button will be disabled, and there would be a status that says " In Use: This APD is currently being locked by another user." Also, the last edited will changed to locked. Side note: I have now decided to remove the name because currently there is no actionable benefit to having the name; users cannot contact the other user in the system. Users will not be able to print in this state.
4. If there is more than one APD, then each locked APD will look like the one above in point number 2.
5. The system will update in real time when an APD has been released, and we will indicate this change with a green success color fade in and out over the corresponding newly available APD. When an APD is released, the APD link will be enabled, the delete button will be enabled, the status of "In Use: This APD is currently locked by another user." will go away, and the locked status will change to last edited. Printing/exporting will then be available on the Export and Submit page.
6. A user can have two or more tabs open of the same APD but they would have to reload the page to keep it up to date.

Use Case 2: Single User Access Workflow from an old link/bookmark

1. Currently, if you use a link for a page in the APD, if you are logged in, you are directly to that page and if you are not logged in you must sign in first then you are directed.
2. In this design, once you get to the page, I anticipate a gradual transition or immediate change to the page hidden by the modal. The call to action on the modal is to go to the dashboard.

When is an APD released

Fortunately, I don't think we have to worry about a user being on an APD indefinitely because the system requires a user to stay active on eAPD to be logged in.

1. User the person in the APD) logs out
2. Session timeout
3. When user 1 navigate out of APD through top and bottom nav
4. Navigates to a different APD in the same tab
5. Just navigates out of the APD in any particular way.
6. Closes window or tab
7. Network outage/timeout: We need a timer in the backend to allow for this.

Additional Design Notes

1. The last edited and locked for editing status should be updated in real time and not triggered by a user refreshing the page.
2. Though it is already implemented, it is important to note that the last edited date is localized by the browser so no additional work is need.
3. Add the full name of MMIS and HITECH to the section labels
4. Just have the ffy shown as a tag instead of MMIS IAPD|FFY 2022-2023
5. Add icons to certain details on the dashboard: temporarily locked for edited, last edited, created and delete
6. Make the delete button red to flag that it is a destructive action when enabled
7. Only show the funding sources available. So, if there is no HITECH, dont show the hitech subheader
8. Add last edited by field

Fontawesome Icons

1. rectangle-xmark for the alert
2. lock symbol
3. lightbulb-on (It is a pro icon, so I couldn’t download it, so I drew it on figma. But I want to know if the dev team has access to it.)
4. clock symbol
   5: user

Status Change Animation

Ty came up with an animation we can use to indicate to the user that a change has been made and a APD is now available or in use by another user. This is what we will be using to transition between the status change and its duration can be a bit longer than a typical autosave page reload.
https://images.zenhubusercontent.com/113234315/f0a359a2-4bb8-4191-a97e-a7cdcdb92c0b/screen_recording_2023_03_30_at_11_43_11_am.mov

[akuas]

@thetif Just an update, I have removed the inline alert.

[akuas]

@jeromeleecms and @SGilliamA1M This ticket is ready for review. Future
@stephanieboydcms for awareness as well.

[akuas]

@jeromeleecms and @SGilliamA1M I have updated the disabled buttons to #5a5a5a, which passes the color contrast test, added last edited by, updated the closing notes and added Ty's animation. So, this ticket is ready to go.

[akuas]

@jeromeleecms and @SGilliamA1M I have updated the disabled buttons to #5a5a5a, which passes the color contrast test, added last edited by, updated the closing notes and added Ty's animation. So, this ticket is ready to go.

[SGilliamA1M]

Thanks @akuas - changes look good.

[jeromeleecms]

Good for dev tickets based on Design Sync and adjustments afterwards.

[thetif]

created dev tickets #4053, #4654, #4655, #4656, #4657, #4658, #4659, #4660

[jeromeleecms]

Everything looks good - just needs to consider how to allow a state admin to force unlock an APD - @SGilliamA1M thoughts on that?

[SGilliamA1M]

@jeromeleecms - definitely worth exploring. I imagine we would first need a means to track and show locked-state APDs in the Admin portal, as well as a control that triggers the unlock capability.

Another question that surfaces is what are instances that would cause an APD to remain locked on the front-end and not the back-end?

[jeromeleecms]

I was thinking something simple - since we are going to be tracking the lock status anyway, can we add something like an "Unlock" option for State Admins above the delete option?

[jeromeleecms]

This is done.