2.0 Feature Toggle Mechanism


The goal for 2.0 was a generic, globally applicable release.  As 2.0 was a fairly fast consolidation of several branches/forks created for specific projects, some features are country specific.  Separating these features into standalone modules was too large of a task, not to mention the lack of a robust modularization framework.  The stop-gap solution for 2.0 is to implement a feature toggle mechanism, where a property set during build time toggles on or off the set of country-specific UI elements. The underlying code and logic remain, ready for use when toggled on.  As explained below, a toggling is accomplished by hiding certain portions of the user interface, such as menu items.

This toggle setting is set for all project-specific code, not for each country-specific project. So there is no toggleOnVIMS, toggleOnJSI, toggleOnMoz, etc.

The build property setting is in the gradle.properties file, called toggleOnCustom.  The actual toggling functionality uses the existing permissions framework to toggle features on or off.  Most of the UI is hidden or shown based on the rights of the logged in user.  Thus, the "toggling" is accomplished simply by denying permissions to the country-specific features. This is enforced by REMOVING the definitions of country-specific permissions (the rights table) at build time. The gradle build simply calls (or does not call) certain SQL scripts to remove (or re-add) those permission definitions to the system. The country-specific permission definitions are always removed during the build–if custom code is toggled on, then they are re-added.

With the removal of permission definitions, certain parts of the system are now hidden or changed.  

Again, this is a stop-gap, cosmetic solution.  A project requiring any number of the toggled off features simply needs to load the appropriate permission(s).


  • Default page at login is changed from the dashboard to /public/pages/index.html
  • Manage distributions link is moved from the Vaccine menu to its own Distributions menu
  • 1.0 reports link is moved from its own Reports menu to under the new Reports menu, with the name Admin Reports
  • Maintenance Requests and Service Contracts are hidden under the Equipment menu
  • Vaccine menu is hidden
  • Almost all reports, with the exception of the User Summary report (in the Admin submenu), are hidden under the Reports menu
  • Vaccine, Manage Custom Reports and Help menu items are hidden (under Administration menu)
  • Seasoning / Rationing Type and Adjustment Basis are hidden (under Configure submenu)
  • In create/edit roles, all of the country-specific rights have been removed and are no longer shown
  • ILS Gateway menu is hidden
  • Dashboard menu is hidden
  • Certain headings have been slightly renamed
    • Equipments menu has been renamed to Equipment
    • Right categories headings in the editing rights for a role have been renamed (e.g.: Admin and general operations rights to Admin and General Operations Rights)


Very little has been changed on the API and backend, as it would take some research to determine what code is country-specific, and APIs that are not published are not supported. Generally the 2.0 stabilization effort is focused on the UI client.


This work has not been done yet, as these features were added by a third party, but permissions were not fully implemented. This work will need to be done for the 2.0 release.

  • Add permission to toggle off Custom Reports DONE
  • Add permission to toggle off Messages under Administration DONE
  • Add permissions to toggle on/off tabs in Other Settings DONE
  • Add permission to toggle off subsections under Facilities edit page DONE
  • Add permission to toggle off Rationing column in Product tab DONE
  • Add permission to toggle off Price Schedule section in Product edit page NOT NECESSARY
  • Fix permission discrepancy of Annual Facility Demography vs. Annual District Demography DONE

Adding Features to Toggle

See the docs/Feature Toggle.md file in the code to understand feature toggling in more detail and how to extend it.

OpenLMIS: the global initiative for powerful LMIS software