Microservice API Analysis for Reporting
- Craig Appl (Unlicensed)
- Antonate Maritim (Unlicensed)
- Clay Crosby (Unlicensed)
Owned by Craig Appl (Unlicensed)
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 service APIs in order to better understand which components of the system should be considered for ingestion. 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.
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 proof of delivery | 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? | Ingested | Notes |
|---|---|---|---|---|---|
| commodityTypes | Returns an array of all commodityTypes in the system | Infrequently | Yes | 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 commodity type | Infrequently | Yes | Not Needed | (Not currently in the API documentation) |
| commodityTypes/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | Yes | Not Needed | 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 | Not Needed | |
| currencySettings | Returns the currency settings for OpenLMIS | Rarely | No | ||
| facilities | Returns an array of facilities. | Infrequently | Yes | Yes | |
| facilities/minimal | Returns an array of facilities with id and name only | Infrequently | No | Not Needed | |
| 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 | Not Needed | |
| 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 | Not Needed | This could help us understand the changes to a particular facility over time |
| facilityOperators | Returns an array of all facility operators | Rarely | Yes | Not Needed | |
| facilityOperators/{id} | Returns a specific facility operator | Rarely | Yes | Not Needed | |
| facilityOperators/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | Yes | Not Needed | |
| facilityTypeApprovedProducts | Returns an array of approved products by facility type | Infrequently | No | ||
| facilityTypeApprovedProducts/{id} | Returns a specific facility type approved product | Infrequently | No | ||
| facilityTypeApprovedProducts/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | No | ||
| facilityTypes | Returns an array of facilityTypes | Rarely | Yes | Not Needed | |
| facilityTypes/{id} | Returns a specific facility type | Rarely | Yes | Not Needed | |
| facilityTypes/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| geographicLevels | Returns an array of geographicLevels | Rarely | Yes | Yes | |
| geographicLevels/{id} | Returns a specific geographic level | Rarely | Yes | Not Needed | |
| geographicLevels/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| idealStockAmounts | Returns an array of idealStockAmounts | Rarely | Yes | Yes | This may change quarterly or annually depending on the country's policy |
| Location | Get local resources (like geographic zones, facilities) as FHIR Location instances. | Infrequently | Yes | Not Needed | We may want to ingest this if we want to ingest FHIR resources. Otherwise, all information is available in other resources. |
| lots | Experimental resource to find lots in the system | Frequently | Yes | Yes | We will not ingest this endoint until it's no longer experimental. (This resource does not have a schema) |
| lots/{id} | Experimental resource to find a specific lot | Frequently | No | Not Needed | We will not ingest this endoint until it's no longer experimental. (This resource does not have documentation) |
| lots/{id}/auditLog | Experimental resource to get all or part of hte resource's audit log | Frequently | No | Not Needed | We will not ingest this endoint until it's no longer experimental. |
| orderableDisplayCategories | Returns an array of orderableDisplayCategories | Infrequently | No | Not Needed | We need to review this. I'm not sure how it's used. |
| orderableDisplayCategories/search | Find orderable categories with matched code. Returns an array. | Infrequently | No | Not Needed | This resource uses a GET method and all other search endpoints use a POST method |
| orderableDisplayCategories/{id} | Returns a specific orderable display category | Infrequenty | No | Not Needed | |
| orderableDisplayCategories/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | No | Not Needed | |
| processingPeriods | Get all processing periods that match the given parameters. The processingScheduleId parameter should not be used together with facilityId and programId parameters because all of them are used to find a processing schedule. Also the facilityId and programId parameters must be used together. This returns an array. | Rarely | Yes | Yes | This changes annually depending on the country's policy |
| processingPeriods/{id} | Returns a specific processing period | Rarely | Yes | Not Needed | |
| processingPeriods/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| processingPeriods/{id}/duration | Returns an integer of the total months in the processing period | Rarely | Yes | Not Needed | |
| processingSchedules | Returns an array of all processingSchedules | Rarely | Yes | Not Needed | This resource does not have a schema. We need to review this. I'm not sure how it's used. |
| processingSchedules/search | Retrieve processing schedule based on the provided parameters. | Rarely | No | Not Needed | This resource uses a GET method and all other search endpoints use a POST method |
| processingSchedules/{id} | Returns a specific processing schedule | Rarely | Yes | Not Needed | |
| processingSchedules/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| programs | Returns an array of all programs | Rarely | Yes | yes | |
| programs/search | Returns an array of programs | Rarely | No | Not Needed | This resource uses a GET method and all other search endpoints use a POST method |
| programs/{id} | Returns a specific program | Rarely | Yes | Not Needed | |
| programs/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| requisitionGroups | Returns an array of requisitionGroups | Rarely | Yes | Yes | This resource does not have a schema. |
| requisitionGroups/{id} | Returns a specific requisition group | Rarely | Yes | Not Needed | |
| requisitionGroups/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| rights | Returns an array of user rights (permissions) | Rarely | Yes | Yes | Yes, assuming we need to replicate rights in the reporting stack. |
| rights/search | Returns an array of user rights based on search criteria | Rarely | No | Not Needed | This resource uses a GET method and all other search endpoints use a POST method |
| rights/{id} | Returns a specific user right | Rarely | Yes | Not enough rights to access the endpoint with administrator credentials. | |
| rights/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | ||
| roles | Returns an array of user roles | Rarely | Yes | Yes | Yes, assuming we need to replicate rights in the reporting stack. |
| roles/{id} | Returns a specific user role | Rarely | Yes | Not Needed | The documentation has this resource listed as /roles/{roleId} which doesn't follow the other syntax |
| roles/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | ||
| serviceAccounts/{token} | Returns a specific service account | Frequently | No | Not Needed | |
| stockAdjustmentReasons | Returns an array of stockAdjustmentReasons | Rarely | Yes | Not Needed | |
| stockAdjustmentReasons/search | Returns an array of stockAdjustmentReasons based on search criteria | Rarely | No | Not Needed | |
| stockAdjustmentReasons/{id} | Returns a specific stock adjustment reason | Rarely | Yes | Not Needed | |
| stockAdjustmentReasons/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| supervisoryNodes | Returns an array of supervisoryNodes | Rarely | Yes | ||
| supervisoryNodes/{id} | Returns a specific supervisory node | Rarely | Yes | Not Needed | |
| supervisoryNodes/{id}/supervisoryUsers | Returns a specific supervisory node | Infrequently | No | Not Needed | |
| supervisoryNodes/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| supplyLines | Returns an array of supplyLines | Rarely | Yes | ||
| supplyLines/searchByUUID | Returns an array of supplyLines based on search criteria | Rarely | No | Not Needed | This resource uses a GET method and all other search endpoints use a POST method |
| supplyLines/{id} | Returns a specific supply line | Rarely | Yes | Not Needed | |
| supplyLines/{id}/auditLog | Returns all or part of the resource's audit log | Rarely | Yes | Not Needed | |
| tradeItems | Returns an array of tradeItems | Infrequently | Yes | Yes | |
| tradeItems/{id} | Returns a specific trade item | Infrequently | Yes | Not Needed | This resource is not documented |
| tradeItems/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | Yes | Not Needed | |
| users | Returns an array of users | Infrequently | Yes | ||
| users/rightSearch | Returns an array of users based on search criteria | Infrequently | No | Not Needed | |
| users/{id} | Returns a specific user | Infrequently | Yes | Future | This resource is not documented and may not exist due to the /users/{userId} endpoint. |
| users/{id}/auditLog | Returns all or part of the resource's audit log | Infrequently | Yes | Future | |
| users/{userId} | Returns a specific user | Infrequently | Yes | Future | This assumes we need to consumer user in |
| users/{userId}/facilities | Returns an array of all supervision facilities associated with a user. To determine which facilities work with which right and program, please use /permissionStrings for mappings. | Infrequently | Yes | Future | |
| users/{userId}/fulfillmentFacilities | Returns an array of facilities the associated user can fulfill. | Infrequently | Yes | Future | |
| users/{userId}/hasRight | Returns a Boolean. Check if the user has a right with certain criteria. | Infrequently | Yes | Future | |
| users/{userId}/permissionStrings | Returns an array of all permissions (in string format) associated with a user. The format is as follows; RightName|FacilityUUID|ProgramUUID for supervision rights, RightName|FacilityUUID for fulfillment rights, and RightName for general rights. | Infrequently | Yes | Future | |
| users/{userId}/programs | Returns an array of programs the associated user supervises. | Infrequently | Yes | Future | |
| users/{userId}/roleAssignments | Returns an array of full information about user's roles and rights. | Infrequently | Yes | Future | |
| users/{userId}/supervisedFacilities | Depricated | Infrequently | No | Future | |
| users/{userId}/supportedPrograms | Returns an array of supported programs the associated user supervises through the home facility. | Infrequently | Yes | Future |
Requisition Service
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.
| Resource /api/ | Description | Frequency of Change | Consider For Ingestion? | Notes |
|---|---|---|---|---|
| availableRequisitionColumns | Returns an array of availableRequisitionColumns | Rarely | Yes | Yes, assuming we want to dynamically display requisition information |
| reports/templates/requisitions | Returns an array of requisition report templates | Rarely | No | |
| reports/templates/requisitions/{id} | Returns a specific requisition report template | Rarely | No | |
| reports/templates/requisitions/{id}/{format} | Returns a generated report based on the template id and format | Rarely | No | |
| requisitions | Returns an array of requisitions | Frequently | Yes | |
| requisitions/periodsForInitiate | Returns a single processing period DTO that's available to initiate the requisition | Frequently | No | |
| requisitions/requisitionsForApproval | Returns an array of requisitions that are currently awaiting approval | Frequently | Yes | |
| requisitions/requisitionsForConvert | Returns an array of requisitions that are currently awaiting to be converted to orders | Frequently | Yes | |
| requisitions/search | Returns an array of requisitions based on search criteria | Frequently | No | This resource uses a GET method and all other search endpoints use a POST method |
| requisitions/submitted | Returns an array of requisitions that currently have "SUBMITTED" status | Frequently | Yes | |
| requisitions/{id} | Returns a specific requisition | Frequently | Yes | |
| requisitions/{id}/print | Returns a PDF of a specific requisition | Frequently | No | |
| requisitions/{id}/statusMessages | Returns an array of status messages for a specific requisition | Frequently | No | |
| requisitiontemplates | Returns an array of requisitionTemplates | Rarely | Yes | |
| requisitiontemplates/{id} | Returns a specific requsitionTemplate | Rarely | Yes |
Stock Management Service
The Stock Management Service provides RESTful API endpoints for creating electronic stock cards and recording stock transactions over time.
| Resource /api/ | Description | Frequency of Change | Consider For Ingestion? | Notes |
|---|---|---|---|---|
| organizations | Returns an array of organizations. This is for administrators only. It requires the permission STOCK_ORGANIZATIONS_MANAGE. Regular users can get the list of sources or destinations they can use through /api/validSources and /api/validDestinations. | Rarely | No | |
| physicalInventories | Returns an array of saved physical inventory. If inventories do not exist, will return empty list. | Frequently | Yes | |
| physicalInventories/{id} | Returns a specific physical inventory | Frequently | Yes | |
| physicalInventoryTemplates | Returns a jrxml physical inventory report template | Rarely | No | |
| reasonCategories | Returns an array of reason categories to choose from, for admin user to configure reasons. | Rarely | Yes | |
| reasonTypes | Returns an array of reason types to choose from, for admin user to configure reasons. | Rarely | Yes | |
| stockCardLineItemReasons | Returns an array of stockCardLineItemReasons | Rarely | Yes | |
| stockCardLineItemReasons/{id} | Returns a specific stock card line item reason | Rarely | Yes | |
| stockCardLineItemReasonTags | Returns an array of stockCardLineItemReasonTags | Rarely | No | |
| stockCards | Returns an array of stock cards, result is an intersection of user rights and request parameters. | Frequently | Yes | |
| stockCards/{id} | Returns a specific stock card | Frequently | Yes | |
| stockCards/{id}/print | Returns a PDF of the stock card | Frequently | No | |
| stockCardSummaries | Depricated | Frequently | No | |
| stockCardSummaries/print | Returns a stock card summary report in PDF format to print. | Frequently | No | |
| stockCardSummaries/noCards | Returns an array of dummy stock card summaries for approved products and lots that don't have cards yet. This can be used by front end to determine what new stock cards can be created. | Rarely | No | |
| stockCardTemplates | Returns a stock card template given the parameters | Rarely | No | I think this is used for UI related display and may be applicable for display in the reporting stack |
| v2/stockCardSummaries | Returns an array of summaries of stock cards, which contains SOH, product name, and other essential information. This will NOT return any line items. (This could be used by front end for list view.) | Frequently | Yes | |
| validDestinations | Returns an array of valid destinations of a program and a facility type. | Rarely | Yes | |
| validReasons | Returns an array of valid reasons based on program and facility type. | Rarely | Yes | |
| validSources | Returns an array of valid sources based on program and facility type. | Rarely | Yes |
Sample API Improvements from Ona
- For referenceData, having an API to accept a single /{id} for the 3 below, it would make it easier to fetch the ISA
- Facility
- Commodity type
- Processing period
- Add field for updatedDate that would indicate the last time a transaction was updated. Particularly, the last time the stockOnHand was recalculated
- If a transaction has a postDate on the 5th of the month but an occurredDate on the 1st of the month, we know that transaction potentially affected all transactions for that orderable at that facility after the 1st of the month
- Right now all we have is occurred date, but when certain data points on a particular transaction can change over time, knowing the last time that transaction was updated would greatly assist us as we keep the stockOnHand field up to date. Without this, we need to reindex bulk data periodically to ensure SoH is accurate (which is not practical at all), or we would need to calculate SoH in the reporting platform.
- Alternative: add field for postDate
- Make “program” an optional parameter for stock cards so we don’t have to hit the API for each program.
- We would still extract the program information, but it wouldn’t be required by the API in order to fetch data.
- This reduces the number of times that we need to query the API
- We can expect up to 5 programs in an implementation
- The data that’s in reporting will retain the program
- Instead of listing the ids of Commodity Type, Trade Item, Facility, etc. on each stock card line item, list the name of those entities directly
OpenLMIS: the global initiative for powerful LMIS software