New to the Project? Check out the O3 Developer Documentation

OpenMRS ESM User Onboarding App

An interactive walkthrough system for O3 that provides guided tours and tutorials to help users learn the system. Built with React Joyride, it features multiple pre-configured tutorials covering essential workflows like patient registration, chart navigation, recording vitals and biometrics, and more.

Features

• Interactive Guided Tours: Step-by-step walkthroughs using spotlight highlighting and tooltips
• Auto-progression: Automatically advance to next step when target elements appear
• Multiple Tutorials: 8 pre-configured tutorials covering core OpenMRS workflows
• Configurable: Customize tutorials through OpenMRS configuration system
• Smart Waiting: Automatically waits for elements to load before proceeding
• Interactive Elements: Support for clickable elements during tutorials

Available Tutorials

1. Basic Overview - Introduction to main dashboard and navigation
2. Registering a Patient - Complete patient registration workflow
3. Patient Chart - Navigate and understand patient chart features
4. Finding a Patient - Search functionality and advanced filters
5. Patient Lists - Create and manage patient lists
6. Recording Vitals - Capture patient vitals and biometrics
7. Starting a Patient Visit - Begin a patient encounter
8. Demo Tutorial - Development and testing features

Development

Prerequisites

• Node.js (v22 or higher)
• Yarn package manager

Running locally

yarn  # install dependencies
yarn start  # start development server

Configuration

Enable tutorials by setting showTutorial: true in your OpenMRS configuration. Customize tutorial content through the tutorialData configuration array.

Step Configuration

Basic Step Properties

Each tutorial step supports the following properties:

• target: CSS selector for the element to highlight
• title: Optional step title
• content: Step description text
• placement: Tooltip placement (top, bottom, left, right, center)
• spotlightClicks: Allow clicking on highlighted elements
• disableOverlay: Disable the dark overlay

UI Control Properties

• hideBackButton: Hide the back navigation button
• hideNextButton: Hide the next navigation button
• hideFooter: Hide the entire footer
• hideCloseButton: Hide the close button

Auto-transition Steps

Automatically advance when target elements appear:

{
  target: '[data-extension-id="some-target"]',
  content: 'Click this button to continue',
  spotlightClicks: true,
  hideNextButton: true,
  data: {
    autoNextOn: '[data-extension-id="next-element"]'
  }
}

The step will automatically proceed when the autoNextOn selector matches an element on the page.