Page tree
Skip to end of metadata
Go to start of metadata


An OpenMRS implementation supports a wide variety of users, each of whom has different needs. Often, particular groups of users only work within a limited area of the application - entering forms, running reports, doing system administration, or viewing patient summaries. However, OpenMRS does not ship with a means for providing custom workflows or views of the system to optimize the experience for such users.

The intention of the Role-Based Homepage module is to start to address this gap. This module allows for administrators to define a custom "Home Page" for each defined Role within the system. These Home Pages may be simply pages that already exist, and which particular users would be best served to have as their default - for example, System Administrators may want the Administration page as their default home. Alternatively, administrators can "author" new pages within the running application for their users. Examples of each of these will be illustrated below.

Installation and Configuration

  • Download from the module repository
  • Grant any required privileges
    • Manage Homepages: Users with this privilege will be able to configure what homepages are assigned to what roles
  • Configure settings:
    • rolebasedhomepage.defaultHomePage: If specified, this will be the default homepage for all users. If unspecified, it will default to a standard OpenMRS homepage


Manage Homepages Dashboard

All administration of Role-Based Homepages can be done via the "Manage Homepages" page, accessible from the Administration section. Within this page, you can view all of the current home pages by role. You can preview the home page for a particular role by clicking the "Preview" link next to a Role. You can also preview the home page that will appear for a particular user by entering a username in the supplied box and clicking the "Preview" button. You can edit the home page for a role by clicking on the Role name. You can also directly configure the default homepage global property from this page.

URL-based Homepages

The first manner in which a Home Page can be defined is by referencing a URL within the system you wish to use. This can be any page supplied by core or by a module. To determine the valid configuration setting, you should first navigate to the page you are interested in within your system, and find the URL of this page in the browser. The page you navigate to will have a URL in the form of: 


In such as case, the home page configuration for this page should be "admin/index.htm" (i.e. you would omit the 


 part of the URL from the specification). An example of this is shown below.

Custom HTML/JSP-based Homepages

The second manner in which you can configure a home page is via custom HTML and/or JSP. This can contain standard HTML and Javascript. It can also contain any valid JSTL expression, JSP Scriplet, or custom tag that is exposed within the standard OpenMRS header and Portlet Controller. This is very powerful, as it allows developers to create a library of portlets that might be added to user dashboards, and for system administrators to configure which of these portlets appear on which role-based homepage, and with what layout. An example of this is shown below:

Basic HTML

Addition of JSTL

Addition of JSP Tags


Once configured, users will see their custom homepage any time they initially log into the system, navigate to 


or click the "Home" link within the OpenMRS Navigation Header. If a particular user belongs only to a single Role that has a custom homepage configured for them, they will always be taken into the homepage for that Role. If, however, a user belongs to multiple Roles, more than one of which has a custom homepage assigned to it, then upon first access each time they log in, the user will need to choose which Role they wish to assume for the course of that session. The system will "remember" this decision for each subsequent access to the home page during the course of the user's session. To reset this, the user can log out and log back in, and they will be prompted to answer this question once again. See below:

Release Notes

  • 1.0: Initial alpha (never released)


Project Lead:

Mike Seaton


Harshini Gudiwada (Google Summer of Code 2009)

  • No labels