GSoC 2024: O3 User Onboarding

Primary mentor

@Piumal Rathnayake

Backup mentor

@Jayasanka Weerasinghe

Assigned to



Implementing user onboarding in the Test 3 and O3 demo environments, as illustrated in these designs, is crucial for introducing users to major features within a typical generic outpatient workflow. By incorporating user onboarding processes, new users can navigate through the system more seamlessly, gaining a better understanding of how to utilize various functionalities effectively. This not only enhances user experience but also ensures that users are equipped with the necessary knowledge to maximize the capabilities of OpenMRS in their outpatient workflows. Additionally, user onboarding can help reduce the learning curve associated with adopting a new system, ultimately leading to increased user satisfaction and productivity.

Project Overview

This project is focused on creating a step-by-step user onboarding process for the new users of OpenMRS, essentially functioning as a tutorial mode or product tour system. So when a new user logs into O3, or when a user navigates to a page that has not been visited previously, it should trigger an interactive guide that will take the user through the features of that specific module/page and introduce those.

For this, we can use things like tooltips, highlighted areas, pop-ups containing text/images/short videos, hotspots, progress indicators, and more. For a better user experience, we can add functionalities like displaying the number of remaining steps, granting users the option to skip the onboarding processes or individual steps, and enabling them to retrigger the tutorials as needed.

You have complete freedom to suggest your approach to implementation, including the libraries and technologies required for your solution. But, it should be implementable on any O3 module and should be easily extendable to all O3 modules.

For the project proposal, we recommend including a small demo with a sample implementation using a selected O3 module (or any other method). Additionally, you can choose an O3 module and outline specific steps that could be highlighted during the onboarding tutorial.

We have already created some designs for the O3 User onboarding process, which can be found here: O3 Zeplin Designs (Refer to the “Tasks – Onboarding” section). You can gain some ideas from these designs. (You can find the Zeplin login credentials here)

Skills Needed

  • A fundamental knowledge of OpenMRS Microfrontends is required.

  • Proficiency in frontend web development, particularly with React, is highly desirable.

Required Skills


Project Rating and length


175 hours


  • 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

Weekly Blog Posts


Blog Post


Blog Post

Week 0

Week 1

Week 2

Week 3

Week 4

Week 5

Week 6

Week 7

Week 8


Week 9


Week 10


Week 11


Week 12



Meeting Notes

Meeting 1: First Mentor Meeting

  • Date : May 16, 2024

  • Participants : Piumal and Jayasanka

Discussion Highlights:

  • Suggested to keep my entire discussions on talk page and documentation in wiki page.

  • Raised questions on where we can keep onboarding mode button (more specifically it goes to UI/UX team) and implementation goes on the esm-core repository.

  • Clarified that we need to set up onboardings on each O3 repo.

  • Asked me to prepare initial milestones for the project.


Meeting 2: Updates for onboarding flows

  • Date : May 23, 2024

  • Participants : Piumal

Discussion Highlights:

  • Suggested to get an early feedback from the UI/UX design team in order to get the designs for onboarding flow and asked me to join the UI/UX design call session on that day.

  • Discussed the multi-route onboarding feature in different pages of O3 modules.

  • Discussed about the the PR I made in patient-registration-module and its difficulties in implementation.


Meeting 3: Initial Steps

  • Date : May 30, 2024

  • Participants : Piumal and Jayasanka

Discussion Highlights:

  • Suggested me to document the steps for the each tutorials as we required to follow up with the design team .

  • Discussed where we can set up the help menu component, so that It can be accessed whole app wide.

  • Got a feedback about the PR to keep the showTutorials enable/disable button temporarily in the configuration.

  • Discussed the designs for the tutorials in Zeplin and Zeroheight.


Meeting 4: Quick Updates

  • Date : June 06, 2024

  • Participants : Piumal

Discussion Highlights:

  • Discussed few technical difficulties regarding the extension and extension-slot

  • Shared the implementation of Help Menu with Piumal.


Meeting 5: Workflows

  • Date : June 11, 2024

  • Participants : Jayasanka and Grace

Discussion Highlights:

  • Shared the updates of previous week with Jayasanka and Grace.

  • Grace had given suggestions on how the user onboardings, also she said that she will be helping on for documenting the workflows.

  • we also had a discussion on how we include patient specific tutorials.


Meeting 6: Better Approach

  • Date : June 20, 2024

  • Participants : Jayasanka and Piumal

Discussion Highlights:

  • Shared the updates of Help menu PR ( specifically working on extensions ).

  • we discussed on how we can setup in the tutorials in core repositories, so that the tutorials can be loaded in the form of extensions.

  • Jayasanka also helped me on the concept of extensions and we pair programmed to keep the sub menu items as an extensions.


Meeting 7: New Architecture

  • Date : June 25, 2024

  • Participants : Jayasanka, Piumal and Grace

Discussion Highlights:

  • we came up with a new architecture - having a separate microfrontend module openmrs-esm-user-onboarding

  • My primary mentor help me to start with the new repository and made a clean repo with Joyride initiated #1

  • we also discussed on how we can have these tutorials loaded on the configuration.

  • I also checked out with Grace to have work on those basic tutorial steps.


Meeting 8: Reviewing the PR’s

  • Date : July 02, 2024

  • Participants : Jayasanka and Piumal

Discussion Highlights:

  • Got the Help menu PR merged.

    • My mentors had gone through other PR’s as well #2 #3

  • I also cleared doubts on how we can handle states between two components. some suggested approaches were :

    • Have common parent, and then pass data via props

    • Passing data with context

  • Jayasanka has also helped me to set up the milestones for the next week.




Project Repos