Work in Progress
This is a work in progress and we will remove this info box when complete.
The OpenLMIS reporting architecture requires an understanding of the microservice APIs. This document is a large scope based on the OpenLMIS v3.3 architecture and includes identifying each microservice, taking a snapshot of the API endpoint, identifying if data changes over time and identifying whether this endpoint needs to be considered for reporting ingestion. Further documentation is available on the components page. This analysis includes
What's included:
- All endpoints that have a GET method
What's not included:
- Auth Service - The auth service focuses on authenticating users. The reporting stack does not have a clear use case for this information.
- Reference UI - The reference UI component does not have endpoints that can be consumed.
- Report Service - The report service primarily focuses on building reports for consumption within the Reference UI. There is no clear use case for this information.
- Notification Service - The notification service only presents an interface for other microservices to send notifications to users. There is no clear use case for this information.
- Endpoints with POST, PUT or DELETE methods will not be included because the reporting stack only consumes data.
Fulfillment Service
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.
| Resource /api/ | Description | Frequency of Change | Consider | Notes |
|---|---|---|---|---|
| orderFileTemplates | Get the template of the order file | Rarely | No | |
| orderNumberConfigurations | Get the configuration for the order number | Rarely | No | |
| orders | Get an array of all orders. Minimal order details are presented | Frequently | Yes | This endpoint is used to get a list of orders so we can query each order by id |
| orders/requestingFacilities | Return UUIDs of all the available, distinct requesting facilities. The supplying facility when provided, it will also filter the available requesting facilities by the supplying facility of the order. | Rarely | No | This may be interesting for streamlined reporting, but if we are consuming each order, we can derive this list in the reporting system. |
| orders/{id} | Get chosen order with details | Frequently | Yes | This Entity changes over time as orders change. Note that there is an "expand" query parameter that could be valuable as well. |
| orders/{id}/export | Export Order to CSV | Frequently | No | |
| orders/{id}/retry | Manually retry for transferring order file via FTP after updating or checking the FTP transfer properties. | Rarely | No | |
| orders/{id}/print | Print all order line items from an order to a csv or pdf file. | Frequently | No | |
| proofOfDeliveryTemplates | Download Proof Of Delivery report template with jrxml format. | Rarely | No | |
| proofsOfDelivery | Get an array of proofs of delivery. | Frequently | Yes | This endpoint is used to get a list of all proofs of delivery so we can query each proof of delivery by id |
| proofsOfDelivery/{id} | Get chosen proofOfDelivery | Frequently | Yes | This Entity changes over time as proofsOfDelivery change. Note that there is an "expand" query parameter that could be valuable as well. |
| proofsOfDelivery/{id}/auditLog | Returns all or part of the resource's audit log | Frequently | Yes | This will be valuable for seeing how a proof of delivery has changed over time. |
| proofsOfDelivery/{id}/print | Print proof of delivery to a pdf file. | Rarely | No | |
| reports/templates/fulfillment | Get an array of all fulfillment report templates | Rarely | Yes | This gets a list of all report templates.This may be useful if we need to display any information to users in a similar way. |
| reports/templates/fulfillment/{id} | Get a specific report template | Rarely | Yes | |
| shipmentDrafts | Get an array of all shipment Drafts, which are shipment files that have not been submitted. | Frequently | No | |
| shipmentDrafts/{id} | Get a specific shipment Draft | Frequently | No | |
| shipments | Get an array of all shipments | Frequently | Yes | This endpoint is used to get a list of all shipments so we can query each shipment by id |
| shipments/{id} | Get a specific shipment | Frequently | Yes | This Entity changes over time as shipments change. Note that there is an "expand" query parameter that could be valuable as well. |
| transferProperties/search | Find transfer properties by facility id (transferProperties are used for FTP and local settings that help the system interact with a third party fulfillment service) | Rarely | No | |
| transferProperties/{id} | Get a specific transfer property | Rarely | No |
CCE Service
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.
| Resource /api/ | Description | Frequency | Consider For Ingestion? | Notes |
|---|---|---|---|---|
| catalogItems | Returns all CCE catalog items that are matching given request parameters by conjunction. | Infrequently | In | This endpoint is used to get a list of all catalog items so we can query each catalog item by id |
| catalogItems/{id} | Get a specific CCE catalog item | Frequently | Yes | This Entity changes over time as the CCE item reports it's status |
| cceAlerts | Get an array of all CCE alerts | Frequently | Yes | |
| Device | Get local resources (like inventory items) as FHIR Device instances. | Infrequently | Yes | We should consider this if we wish to consume FHIR resources compared to catalogItems/{id} Note that this just lists the device specifics, not the status. |
| inventoryItems | Get an array of all CCE inventory items | Infrequently | Yes | This endpoint is used to get a list of all inventory items so we can query each inventory item by id |
| inventoryItems/{id} | Get a specific CCE inventory item | Frequently | Yes | This Entity changes over time as the inventory item is updated. |
| cce | Get the version of the CCE endpoint | Infrequently | Rarely |
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.
| Resource /api/ | Description | Frequency of Change | Consider For Ingestion? | Notes |
|---|---|---|---|---|
| commodityTypes | Returns an array of all commodityTypes in the system | Infrequently | Yes | This endpoint is used to get a list of all commodityTypes so we can query each commodityType by id |
| commodityTypes/{id} | Returns a specific commodityType | Infrequently | Yes | (Not currently in the API documentation) |
| commodityTypes/{id}/auditLog | Returns the auditLog for a specific commodityType | Infrequently | Yes | This could help us parse changes to the commodityType |
| commodityTypes/{id}/tradeItems | Returns an array of Trade Item UUIDs that may fulfill for the given commodityType | Frequently | Yes | |
| currencySettings | Returns the currency settings for OpenLMIS | Rarely | No | |
| facilities | Returns an array of facilities. | Infrequently | Yes | |
| facilities/minimal | Returns an array of facilities with id and name only | Infrequently | No | |
| facilities/supplying | Returns an array of facilities that are supplied by the same supervisory node | Infrequently | No | (This API endpoint has poor documentation and no schema) |
| facilities/{id} | Returns a specific facility | Infrequently | Yes | |
| facilities/{id}/approvedProducts | Returns an array of full or non-full supply approved products for this facility | Rarely | Yes | |
| facilities/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | Yes | This could help us understand the changes to a particular facility over time |
| facilityOperators | Returns an array of all Facility Operators | Rarely | Yes | |
| facilityOperators/{id} | Returns a specific Facility Operator | Rarely | Yes | |
| facilityOperators/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | Yes | |