Use Cases
Common Use Cases the solution must address. Assumes definition of terms, like "Reference Distribution"
I have used the terms (which are capitalized throughout the document) based on the definitions in OpenLMIS v3 Architecture Overview.
Use Case 1: Project deploys "vanilla" OpenLMIS Reference Distrubution
For this simple case, we want to deploy the reference distribution. No additional modules or enhancements
- Seeding data?
- Configuration: email, db connection, and other items typically found in default.properties
In this case, the implementer would fork the Reference Distribution repository, configure deployment, and deploy all of the Independent Services and the Reference UI.
For seeding data, since each Independent Service manages its own data in its own logical data store, it is in charge of seeding data. (The physical data store information would be in the Reference Distribution configuration, most likely pointing to an external PostgreSQL database.) There will be some sort of script or task that seeds data.
Configuration will be managed in the Reference Distribution repository.
Use Case 1a: Project updates "vanilla" OpenLMIS installation to a newer version
A project has deployed the stock OpenLMIS Reference Distribution. Over time, updates were made to the Reference Distribution services, e.g. updates to Requisitions. The project now wishes to update the installation to use the newer services. Must consider DB migration, etc.
In this case, the implementer would get new versions of the images of each Independent Service that needs to be updated. The new images may have migration scripts that need to be run against their respective logical data stores.
Use Case 2: Project creates new Independent Service, deploys as part of Reference Distribution
A project enhances the OpenLMIS Reference Distribution with a new service and deploys it. The module is not part of the Reference Distribution, but is published and available for others to include in their own distribution. Use case should include how other projects obtain and leverage this module.
In this case, the implementer would create a new Independent Service image, based on a provided template in a separate repository, most likely forking the repository. They would add any necessary database migrations and seed data to their own logical data store. If other projects would want to obtain and leverage the module, they can publish their repository and/or publish their image.
If the new Independent Service has a UI component to it, create a new UI module, based on a provided template. Add code to the module to add any new UI necessary. Fork the Reference UI (which is just a framework to compose UI modules), and add the new UI module to its configuration.
They would also fork the Reference Distribution repository, configure deployment to include the new Independent Service, and deploy all of the Independent Services and Reference UI.
Use Case 3: Project extends a core domain model
As an implementer, I want to add several new fields to a Facility record, say "Color", "Max Occupancy" and "Chairs", an n-length list of chairs available at the facility (this is simply non-sense data for this use case). OpenLMIS should define a means to persist these new fields in the database, and retrieve them with RESTful calls, and use them in standard queries (e.g. return all facilities where color == 'blue').
Core domain models, such as Facility, will be accessible in a Core Domain Independent Service. For core domain models that are expected to be extended, an ExtraData property will be provided, where projects can add new fields. Projects will be able to do CRUD operations on the ExtraData property through REST API calls. It has not been determined whether this extra data will be queryable, but possible approaches for ExtraData seem promising for supporting it (e.g.: can query json columns in Postgres).
Use Case 3a: Project updates UI for a core domain extension
A project has extended the Facility record as described in the above Use Case 3. How is the reference Facility UI screen extended to display these new fields? Note the potential data types that the UI might need to accommodate, e.g. "Max Occupancy" as an integer, Color as a color choose or set of RGB values, and Chairs is a selection list widget.
For core domain models that are expected to be extended, their UI component would already have some way to parse the ExtraData JSON for "primitive" types (integer, text, etc.), to display. For types that are constrained by a set of options, the options will need to be provided somewhere(?).
For any UI changes that are more complex, or if the look and feel of the UI needs to be changed for these new fields, the corresponding reference UI module will need to be forked and modified.
Use Case 4: Add a new service -- Informed Push -- as part of Reference Distribution
We want to update the reference distribution with a new capability. For this example, say it is Informed Push
- Update reference distribution
- Update docker image configuration to add new docker instance for Informed Push. Will hold image of the new Spring boot application
- Starting published Spring boot application template, create new Spring boot application. Write informed push logic here
- If extensibility is foreseen, instead write informed push as a Spring module
- UI: create new UI component (starting from published UI template). Update reference UI application to include
This use case is mostly the same as Use Case 2. The main difference is that once the new Independent Service has been created, published and reviewed by the OpenLMIS community, the Reference Distribution and Reference UI would be updated to include the new Independent Service, and those repositories would come under the governance of the community.
Use Case 5: Adding a Strategy to an Independent Service
How does a project insert their own strategy to an OpenLMIS extension point?
Some Independent Services will have extension points, where its Service can be extended by an Extension Module. These extension points will most likely be Java interfaces, where the Service will run a strategy. There will be a default strategy implemented, but can be overridden.
A project can insert their own strategy by creating an Extension Module, based on a provided template in a repository. This Extension Module will have a Java class that implements the extension point interface with a new strategy. The Extension Module is packaged with the rest of the Independent Service, its Spring context will be active in deployment, and the new strategy will be used.