O3 Workspace v2 migration: requesting feedback for migration strategy

Development
1

Hi all,

Over the past several months, we have been working on the workspace v2 system in O3. The new workspace system has improvements including:

  • clear definition of workspace grouping hierarchy, with the introduction of “workspace windows”. Workspaces belong to workspace windows, and workspace windows belong to workspace groups.

  • sharing of data (props) between workspace within the same window and within the same group.

  • support for child workspaces

  • better handling of scenarios requiring prompting for unsaved changes: when closing a workspace, when opening an already-opened workspace (with different props), or even when opening a workspace while a different (but related) workspace is opened.

For a more detailed explanation, see the Workspace v2 migration guide.

We are currently in the process of migrating apps to use the new system, and are hoping to complete the migration in time for the 3.6 release. The migration in the Dispensing app, which was relatively simple, has already been done. Another PR for the Service Queues app, which is more complex as it uses workspaces from the patient chart app and the patient search app, is pending. We are also in the middle of migrating other apps in openmrs-esm-patient-management and openmrs-esm-patient-chart.

One huge challenge though, is the migration of Patient Chart workspaces, as a lot of them are also used outside of the Patient Chart. For example, the “Start visit” workspace is used in the service queues app, the order basket workspaces and the clinical forms workspaces are used in the ward app. Of the 19 workspaces defined in openmrs-esm-patient-chart, at least 12 of them are also used outside. The migration, unfortunately, is backwards incompatible and cannot be done piecemeal, as the workspaces all shared the same workspace group.

I have 2 pending PRs here and here for this migration of the Patient Chart. The latter one was intended to be a consequential breaking change, literally breaking every app that uses patient chart workspaces. While this will be incredibly disruptive, I believe that, with help from the community, we can resolve these issues in a week or so. This is especially true if we can have at least the Service Queues app PR go in and demonstrate that the new workspace system works as expected when using workspaces from different apps.

An alternative would be that we make two copies of every Patient Chart workspace, one in the old workspace system and one in the new. However, doing so requires us to rewind a good portion of some of the refactoring around the order basket store and the clinic forms workspace, and will likely drag out the migration process.

I hereby propose the following steps for the migration:

  • Get this PR, which refactors patient chart workspaces to only receive the patient and visit objects via props, approved and merged. This is necessary prerequisite to the actual workspace migration.
  • Get this PR, which migrates the Service Queues app to workspace v2, approved and merged. This serves as a good test that the new workspace system functions as expected in a more complex case.
  • Get this PR, which migrate all patient chart workspaces, approved and merged. This will be the huge breaking change.
  • Work with the community to fix apps requiring patient chart workspaces.

(In between each of those steps are probably some bug fixes and stabilization.)

Please let me know of any concerns or feedback. Thanks!

cc: @mseaton @mogoodrich @ibacher @dkigen @dev4 @dev5

4 Likes
2

Thanks @chibongho1! I concur with your proposed approach. This will mean that most apps in the RefApp will get a major version bump, but that is, after all, exactly why we use SemVer.

It would be great to hear from, e.g., @PalladiumKenya, @METS, @michaelbontyes and others on their views of this.

The key question here is whether making the shift to the new workspace system for 3.6 instead of 3.7 will cause any implementation serious hardship. If not, we’d prefer to get it over and done with.

As Chi Bong says, he is willing to help work with the community and, of course, our Global Product Support Team will be very happy to help with any migration issues this raises.

7 Likes
3

@jaba @akileng56 @daphine

1 Like
4

I am on board with the proposed approach. This enables us to leverage this alot on the RDE because the its one of the main reasons workspaces V2 was started.

1 Like
5

Update: The last pending PR for the patient chart has been approved. I will be merging it in soon.

The migration work is tracked under this epic. Feel free to update the ticket if your app is missing there. Thanks to @muppasanipraneeth19 and @gcliff for already contributing to the migration!

Apps that use workspaces from patient chart and have not migrated to workspace v2 will break. For help with the migration, please refer to the migration guide. I will also be active on Slack to respond to questions / issues. Thanks for your patience for putting up with (hopefully short) breakages in dev3.

3 Likes