GSoC 2024 : O3 User Onboarding Project Updates

Hello Everyone,

I’ve been selected for Google Summer Of Code 2024 to work on project : O3 User Onboarding. I will use this thread to share the project updates and for general communication purposes.

Primary mentor: @piumal1999

Backup mentor: @jayasanka


  • Identify the processes that require user onboarding tutorials/guides
  • Identify the suitable frameworks/libraries needed to implement the system
  • Building a user onboarding system which can be implemented on any O3 module



Wiki page

cc : @grace @dkigen @hadijah315

gsoc2024 openmrs

1 Like

I’m excited to share my community bonding journey through this blog. Week 1 started with an excellent GSoC orientation session led by @jayasanka and @grace.

1 Like

In Week 2, I had my first amazing meeting with my mentors

Community bonding WrapUp blog


Project update | Community bonding period 2024-05-04T18:30:00Z2024-05-25T18:30:00Z

  • I had call with my mentors on 2024-05-15T18:30:00Z and 2024-05-22T18:30:00Z, we discussed about the project plan and the timeline. Also discussed about the following things:

    • Where all we need to show these user onboarding flows?
      • Suggestion: Identify in perspective of an experienced developer and a normal user who is beginner on OpenMRS
    • Regarding the designs of these workflows across all O3 modules
      • Suggestion: Get an early feedback from the UI/UX design team in order to get the designs for onboarding flows.
      • Suggestion: Try to join in the UI/UX design call sessions.
    • Where we can keep onboarding mode button? (which is triggered manually by the user)
      • Suggestion: This more specifically it goes to UI/UX team and implementation goes on the esm-core repository.
    • Create a JIRA epic for the project.
  • Read through some docs of React Joyride library and made a sample draft PR

  • Updated the project wiki page


I noticed that for the flow of tutorials , Is there any patient specific tutorial flow for the Walkthroughs in the tutorials?

consider If I’m in home page and I need to see onboardings for order-basket, how will the onboarding flows from home page to order-basket page listed in the tutorials section?

cc: @ibacher @vasharma05 @dkigen @jayasanka @piumal1999 @dkayiwa

I had a conversation with @ibacher today about the best location and approach for defining these tutorials. Here’s a summary of what we came up with:

Apart from having onboarding tutorials in O3, the primary beneficiaries would be implementors, such as those in implementations like Kenya EMR. Therefore, these tutorials should be configurable.

The technical architecture would involve an extension mounted during the initialization of O3. This extension will include a configuration schema that allows developers to provide a set of walkthroughs in a JSON array. Each tutorial would be loaded into the Tutorial modal in the help menu. When a user clicks on a specific tutorial, it will guide them step by step.

A sample configuration would look like this:

    tutorials: [
            "name": "Patient Registration",
            "description": "A description",
            "steps": [
                    "target": ".register_button",
                    "content": "Click this button to navigate to the registration page"
                    "target": '[aria-label="Contact Details Section"]',
                    "content": "Here you can update the patient's contact information."
            "name": "Basic Tutorial",
            "description": "Lorem ipsum",
            "steps": []

Since this feature is still under development, we can house it in a new repository. Once we have made significant progress, we can consider moving it to an appropriate monorepo.

Here are some screenshots from the proposed design to give you more context:

cc: @vijaykv @piumal1999 @grace


Thanks @jayasanka for your input

1 Like

After doing some experiments with React Joyride, I’ve found some interesting things that could be helpful when implementing this feature:

  • The <Joyride /> component doesn’t need to wrap the elements we’re using for the tutorial. Even when Joyride is set up in a deeply nested child component, it can still target any rendered element in the application.

  • This flexibility allows us to set up Joyride in a separate microfrontend module dedicated to tutorials. We can configure the route in routes.json to ensure it’s always rendered, similar to what we did with the help-menu button.

  • This will also allow us to keep all the tutorials in one place (for now), so we can continue development without affecting the other microfrontend apps or monorepos.

  • Since most tutorials in OpenMRS will span multiple routes (because almost everything will start from /home), we need to find a good way to handle multi-route tutorials.

Anyway, I’ve created this brief demo showcasing a sample multi-route tutorial with a custom callback function and shared state:

The code can be found here: GitHub - Piumal1999/openmrs-esm-tutorials-app

This approach is successful up to some point. But the most challenging part would be managing the state. Also, the custom callback handler needs to be carefully designed and implemented to handle various scenarios across different tutorials. (PS: I’ll try to comeup with some sample scenarios to explain this)

cc: @jayasanka @vijaykv


Fantastic demo, @piumal1999! I really like the highlight effect, it matches our onboarding designs perfectly. Also, you were right about not needing to wrap anything; it turns out that was a misunderstanding on our part. I realized this too, which is why I came up with the architecture mentioned above. Apologies for not mentioning it earlier.

Just to reiterate, the tutorials can be provided as config, so the tutorials for O3 will always be in the esm-onboarding app (as the default config). This means implementers can easily add or modify tutorials as needed.

I created a new repo for this project. @piumal1999 could you please push your changes to this?


Agreed, the highlighting looks really nice @piumal1999 !

Thank you so much @jayasanka for explaining how these will be configured, and for kicking off that repo. Looks like someone needs to clean out all the esm-template-app generic content from it though :wink: Maybe Vijay can do that?

It’s so helpful to see the sample JSON file. Where do you expect this will live in the app? Would that be here? openmrs-esm-user-onboarding/src/resources/resources.component.tsx at main · openmrs/openmrs-esm-user-onboarding · GitHub

@grace The repo is just a fresh copy of the template and has nothing on it yet. Piumal created a cleaned-up demo earlier here. We need to move it to the new repo: GitHub - Piumal1999/openmrs-esm-tutorials-app

here are the steps from Piumal’s demo. Those have to be cleaned up by removing unnecessary properties and probably should be moved to a separate file.

An ideal structure would look like this:


@jayasanka since this is a separate microfrontend module, can’t we use it without creating an extension? Implementors can choose not to install the module by updating the SPA config file. In dev3, we can keep the module under a feature flag. WDYT?

Yes, my apologies for the confusion in calling it an extension. It will function more like a page (I understand this might sound unusual, but it’s for a specific use case). It will be rendered consistently across all pages, similar to the example provided here:


2024-06-17T18:30:00Z2024-07-05T18:30:00Z Updates

  • Came up with a new architecture to have user onboardings into a separate microfrontend module openmrs-esm-user-onboarding.
  • Got the Help menu PR merged which is the entry point for having tutorials.
  • Completed the milestones till 2024-07-02T00:00:00Z
  • Opened few PR’s in openmrs-esm-user-onboarding repo related to tutorial extension and tutorial modals :

A Sample Demo :