Module Management Specification

Most emergency management organizations have a series of pre-defined processes, tools, and roles. For an application to be a viable option, it must be configurable to the point of enabling organization-specific modules to be installed and maintained independent of other system modules. This problem supports the creation of a symfony module manager and the changes required to the UI menu to enable, disable, install and potentially upgrade Sahana Agasti modules.

Design and Functional Requirements

Reference Information
Name of Design & Functional Preparer: Chad Heuschober
Name of Other Contributors: Darlene McCullough
Last Updated: 3.19.2011

Note on contribution: Please feel free to fill out sections of the specification as this project is a collaborative effort; however, if you feel your ideas could be in conflict to previous ideas or you want to change sections already fleshed out please use the discuss tab first and find consensus with others working on this module or section.


At this point, the basic framework for packages has been established in apps/frontend/lib/packages however, existing legacy code (prior to packaging) needs to be separated back into packages


The City of Bob uses a proprietary hospital management system known as BobHealth developed in Fortran over thirty years ago. Their operational plan for a biological attack requires Sahana Agasti to interact with BobHealth. As a result, the City of Bob develops an agBobHealth module for Sahana Agasti. Because the City of Bob doesn't wish to fork Sahana Agasti and wants to be able to benefit from global Sahana Agasti updates, they need a system to manage their module independently.

Use Case

User Story 1: agBobHealth is Developed, Packaged, and Installed

The agBobHealth developers, following a series of pre-defined metadata and packaging guidelines create an agBobHealth package that works against the current Agasti Mayon version. A City of Bob (CoB) administrator downloads the module, signs into Sahana Agasti, and goes to the module management page. There, the systems staffperson uploads the module which undergoes a sanity check before asking for an installation confirmation. Once confirmed, agBobHealth is installed in a disabled state. To see what the package actually did, our diligent sysadmin dials into a terminal, checks the Agasti folder structure, and notes that the package is self-inclusive, even post-install, with all the relevant files still in one location. Returning to the Agasti screen, our sysadmin refreshes the module manager to see that the agBobHealth module is installed, that is it currently recognized by the system as being version 1.0, and is disabled. The sysadmin clicks a link to enable the module and the plugin is enabled with changes reflecting in the system menu, where module features and sub-features can be accessed as well as the module management page where the module is now shown to be enabled.

User Story 2: agBobHealth has a Major Bug

Following its installation, the BobHealth Administrators started noticing major performance problems. It turns out that agBobHealth had a bug and was querying BobHealth thousands of times per second. Since Sahana Agasti and BobHealth both have duties outside of their integration and BobHealth needed to keep its API open for other consumers, the Sahana Agasti administrators agree to temporarily disable agBobHealth until the bug can be fixed. The Sahana administrator returns to the module management screen and disables agBobHealth. Immediately, all agBobHealth functions stop and BobHealth is no longer under high load from Sahana Agasti.

The agBobHealth developers work all night to develop a fix. They soon find the missing comma and send a new version of agBobHealth along, version 1.1. The system administrator returns to the module management screen and uploads agBobHealth 1.1. The system checks for agBobHealth and discovers that a previous version exists. It asks the administrator if he or she wishes to upgrade agBobHealth from v 1.0 to v 1.1. The administrator agrees, and the system continues with the upgrade, porting any relevant agBobHealth configuration or settings from agBobHealth 1.0 to agBobHealth 1.1.

Upon upgrade completion the module manager still lists agBobHealth as disabled but shows the new version number (1.1). The administrator re-enables the agBobHealth plugin and the old features, and new ones appear.

User Story 3: An Ill-Informed User attempts a Regression

To fix the issues in agBobHealth 1.0, the agBobHealth developers disabled a key piece of functionality that resulted in the bug. A user with administrator privileges, unaware of the 1.0 bug, has noticed that this functionality is missing in agBobHealth 1.1. To solve this the user attempts to “upgrade” to agBobHealth 1.0 using the module manager. When the user uploads agBobHealth 1.0 the Agasti module manager version and sanity check sees that agBobHealth 1.1 is already installed and fails the upgrade, informing the user that regressions are not allowed.

User Story 4: An agBobHealth Extension Appears

Because agBobHealth proved to be so popular, it saw several months of strong development and was developed up to version 1.4 with a 2.0 version on the horizon. At that point, a talented developer realized that agBobHealth could also be used to syndicate BobHealth data to the City of Bob's Medical Examiner's Office. This developer creates agBobHealthMe to satisfy this need.

The Sahana Agasti administrators in the City of Bob think agBobHealthMe is a great extension for their functionality and decide to install it. Upon module upload, however, they are told that because their agBobHealth version is only version 1.1, they can't install agBobHealthMe. Not wishing to upgrade more than is necessary the CoB administrators grab the newly released 2.0 version of agBobHealth and install it. Unfortunately their Sahana Agasti installation is rather old and, when they attempt to install agBobHealth 2.0, they are instructed to upgrade it. Following successful upgrades of Sahana Agasti and installation of agBobHealth 2.0, they attempt to install agBobHealthMe only to discover it doesn't recognize agBobHealth's version (v2.0) and can't install. Realizing they should have read the release notes in agBobHealthMe, they return to the files to discover that agBobHealthMe only works with agBobHealth versions 1.3 through 1.4.

Knowing that they can't regress, the administrators return to the backups they made prior to the installation of agBobHealth 2.0. This time the administrators install agBobHealth v1.4 and, upon attempt, realize they have satisfied the dependency requirements of agBobHealthMe.

User Story 5: agBobHealth Just Can't Get a Break

In version 1.4.2, agBobHealth introduced a bug that forced administrators to disable it while an update was being prepared. While disabled, agBobHealthMe, as a module dependent on agBobHealth, was also disabled until the bug was fixed and agBobHealth was brought back online.

User Story 6: agBobHealth and agBobHealthMe Merge

Deciding there was no reason to develop two different branches, the developers of agBobHealth and agBobHealthMe decide to merge their code into the upcoming agBobHealth 2.1 release. Since this release will not work with agBobHealthMe, the administrators must uninstall agBobHealth me. They go to the module manager and click the uninstallation button of agBobHealthMe. They are asked to confirm their selection, which they do and, as a result, agBobHealthMe is removed from the Sahana Agasti installation, it's folders destroyed, and the tables it owns, dropped from the database.

Description and Constraints

Modules must live in their own directories and have their own data tables (without changing existing table structures). Modules must also be aware of their versions and version dependencies with other Sahana Agasti versions and core components.

Extra Credit

  * Build a package manager with access to a central repository of modules

  • Do not allow the uninstallation of core modules


<What shouldn't this piece do?>

Open Issues

<Recognized problems, holes in the design, and known issues>


<What screens should the user see? How should the work flow through the module? Good to include some sketches or pictures.>

Technical Specifications

Reference Information

Reference Information
Name of Design & Functional Preparer: Name
Name of Other Contributors: Names
Last Updated: Date

Note on contribution: Please feel free to fill out sections of the specification as this project is a collaborative effort; however, if you feel your ideas could be in conflict to previous ideas or you want to change sections already fleshed out please use the discuss tab first and find consensus with others working on this module or section.

QR Code
QR Code agasti:mayon:developer:module_management_spec (generated for current page)