OpenLMIS v3 uses a micro-services Architecture with different services each providing different APIs.
Each component below has its own Git repository, API docs and ERD. Many services below also have a corresponding UI component (e.g. Auth UI, Requisition UI). The Reference UI builds all of these UI components together into one web application.
Logging into the Live Documentation¶
The live documentation links below connect directly to our Swagger docs on our CI server. To use the API you’ll first need to get an access token from the Auth service, and then you’ll need to give that token when using one of the RESTful operations.
Obtaining an access token:
- go to the Auth service’s POST /api/oauth/token
- click on
Authorizein the top right of the page
- in the box that has popped-up, enter username
- enter the username
Try it out!
- In the
Response bodybox, copy the UUID. e.g.
a93bcab7-aaf5-43fe-9301-76c526698898to use later.
- Paste the UUID you just copied into any endpoint’s
Auth Service provides RESTful API endpoints for Authentication and Authorization. It holds user security credentials, handles password resets, and also manages API keys. It uses OAuth2. The Auth Service works with the Reference Data service to handle role-based access controls. (See the Auth Service README for details.)
Fulfillment Service provides RESTful API endpoints for orders, shipments, and proofs of delivery. It supports fulfillment within OpenLMIS as well as external fulfillment using external ERP warehouse systems.
The Cold Chain Equipment (CCE) Service provides RESTful API endpoints for managing a CCE catalog, inventory (tracking equipment at locations) and functional status. The catalog can use the WHO PQS.
The Notification Service provides RESTful API endpoints that allow other OpenLMIS services to send email notifications to users. The Notification Service does not provide a web UI.
Reference Data Service¶
The Reference Data Service provides RESTful API endpoints that provide master lists of reference data including users, facilities, programs, products, schedules, and more. Most other OpenLMIS services depend on Reference Data Service. Many of these master lists can be loaded into OpenLMIS in bulk using the Reference Data Seed Tool or can be added and edited individually using the Reference Data Service APIs.
The Reference UI is a single page application that communicates with OpenLMIS Services to provide a user interface for interacting with OpenLMIS. This UI aims to be modular, extendable, and provide a consistent user experience. It is called a ‘reference’ because implementations may use and/or customize it to their local needs.
The Reference UI is state-driven, meaning the browser’s URL determines what is displayed on the screen. Once the application starts, the browser’s current URL is parsed and used to retrieve data from OpenLMIS Services. All retrieved data populates HTML-based views, which are displayed in the user’s browser and styled by CSS.
The Reference UI is built in a modular way from multiple other UI repositories that are tied together into one single page application. The Reference UI provides the build system, and it uses other repositories to provide collections of layouts and components along with feature-specific repositories (e.g. Auth UI, Requisition UI) to provide the screens that users interact with for different features of OpenLMIS.
Core technologies used to build the UI are:
- Docker provides environment encapsulation
- NPM is the package manager
- Grunt orchestrates the application build process
- Sass is used to generate CSS
- For unit testing, Karma is the test runner and Jasmine is the assertion and mocking library
- Nginx runs the OpenLMIS-UI within the OpenLMIS micro-services framework
Primary libraries used within the UI are:
- AppCache allows the application run in a browser while offline
- AngularJS v1 is the application framework
- Angular UI-Router provides URL routing
- PouchDB stores data for offline functionality
Documentation for the Reference UI:
The Report Service provides RESTful API endpoints for generating printed / banded reports. It owns report storage, generation (including in PDF format), and seeding rights that users may be given.
The Requisition Service provides RESTful API endpoints for a robust requisition workflow used in pull-based supply chains for requesting more stock on a schedule through an administrative hierarchy. Requisitions are initiated, filled out, submitted, and approved based on configuration. Requisition Templates control what information is collected on the Requisition form for different programs and facilities.
Stock Management Service¶
The Stock Management Service provides RESTful API endpoints for creating electronic stock cards and recording stock transactions over time.