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 For Ingestion?	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 of Change	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
1. 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