Request for extension points of Stockmanagement service

For Mozambique SIGLUS system, we need some extension points of Stockmanagement service to do customization. Below is the list:

  • OrderableFulfillReferenceDataService.java
  • AdjustmentReasonValidator.java
  • FreeTextValidator.java
  • UnpackKitValidator.java
  • StockCardRepository.java
  • StockCardLineItemRepository.java
  • PhysicalInventoriesRepository.java

As we are using OpenLMIS v3.9, so we hope you can provide a point release based on the stockmanagement service v5.0.2.

Besides we also have two questions:

  1. Is it possible to create extension points on Controller ? As we need to add some @RequestParam or change some logic in Controller in some cases.
  2. We need add additional query methods in Repository, for example: add findByFacilityIdAndOrderableId in StockCardRepository, should we request here to ask OpenLMIS community add new APIs or we create a new Repository (like below) in our new service directly.
public interface SiglusStockCardRepository extends JpaRepository<StockCard, UUID> {
  List<StockCard> findByFacilityIdAndOrderableId(
      @Param("facilityId") UUID facilityId, 
      @Param("orderableId") UUID orderableId);
}

Thank you for this request, @yinshangwei. I do think that you should plan on upgrading to the currently released version of the Stock Management service (5.1.0) for this work. This version was tested to work with the rest of the v3.9 release and should not present an issue and this will make the upgrade process easier. Is that possible?

@Klaudia_Palkowska Can you investigate how we can get these extension points created and incorporated into the service quickly?

cc @joshzamor

Thanks Wes, I think it is possible to upgrade Stock Management service to 5.1.0, but I need check the effort to do this part of work, and we also need some time to do some regression testing for our QA after the upgrade. Ideally, if you can provide a point release based on the Stock Management service v5.0.2, it is probably the best option for us at the moment. And we can upgrade to OpenLMIS v3.10 at some time in future.

By the way, about two questions, could anyone kindly give me a reply.

@yinshangwei Here you have an example for extension point and documentation.

Answering your questions:

  1. I’m not sure if it’s possible to override the controller in that way (adding new request param). Probably the easiest option would be adding a new endpoint in your extension service.
  2. I don’t know if you will be able to access the database and stock management codebase in case of adding a new query method in your service. If not, probably adding an option to search stock cards by facility and orderable would need to be added to the core OpenLMIS. That would enable you to fetch proper data using the endpoint. In that case, the request and approval from the OpenLMIS community are needed.

@joshzamor or anyone else - please correct me if I’m wrong.

Besides that, I need to mention that actually, 5.1.1 is the latest released version of Stock Management.

@Klaudia_Palkowska Thank you for your response.

Probably the easiest option would be adding a new endpoint in your extension service.

For example, if the extension service means “openlmis-example-extension”, then the new endpoint need be configured in “openlmis-example” service “api-definition.yaml” file, so that consul can register it. Then we need OpenLMIS community to modify the “api-definition.yaml” file.
If the extension service means our new customize service, then we need copy some source code of OpenLMIS v3 and do the modification. But this is not suggested by OpenLMIS community.

I don’t know if you will be able to access the database and stock management codebase in case of adding a new query method in your service.

Yes, we can do that, but I I’m not sure if this way is recommended by OpenLMIS community.

Besides that, I need to mention that actually, 5.1.1 is the latest released version of Stock Management.

Yes, I’m clear about this. As I mentioned, we are using OpenLMIS v3.9, so the stockmanagement service version is 5.0.2.
Link: https://github.com/OpenLMIS/openlmis-ref-distro/blob/rel-3.9.0/.env

Hi @yinshangwei,

Thanks @Klaudia_Palkowska and @ibewes.

Generally, to change the @RequestParameter, no. The extension point mechanism is intended to change the behavior of an existing service and that service’s API. So if you wanted to change the API, the extension point mechanism wouldn’t let you do that. We could look at alternatives here: perhaps the API change is a natural one we could accept directly or if it’s a search/response type request we could look at changing it to a POST where the query parameter’s were moved into the body of the request, allowing for more extension.

If you’d like to change just the behavior of that Controller though, then generally yes - we should be able to do that through an extension point. If you’d like help with how this could be done I’d need to know more about the desired behavior you see, and what you’d want to change it to.

If you’re using the extension point mechanism, you should be able to create a new repository directly. If you’re creating a new Service, then no, you wouldn’t have access to Stock Management’s database.

What @Klaudia_Palkowska and @ibewes are pointing to is a policy we have that says we don’t branch the code, but rather we release fixes and extension points in the latest version. Every service in OpenLMIS follows semantic versioning and so while the version released in OpenLMIS v3.9 of Stock Management was v5.0.2, the latest version of Stock Management is v5.1.1. Any extension points or other pieces would come in a version after v5.2.x. This should be easy for you to adopt in OpenLMIS Ref Distro v3.9, as by the semantic version of the service it’s backward compatible - i.e. the Major version is still v5.x.x.

Let us know what other questions we can help answer.

Best,
Josh

@joshzamor Thank you very much. About the stockmanangement service version, it will be OK for us to use the latest version if it’s compatible with OpenLMIS v3.9.
I list the new extension points and APIs which we need added in stockmanangement service.
Please help review. Thanks.

Extension Points:

  • OrderableFulfillReferenceDataService.java
  • AdjustmentReasonValidator.java
  • FreeTextValidator.java
  • UnpackKitValidator.java

New APIs:

  • query List of StockCard in stock_cards table, searched by facilityId.
  • query List of StockCard(include SOH data) in stock_cards table, searched by facilityId and orderableIds list.
  • add a new attribute createdtime in stock_cards table, and query StockCard(with createdtime) in stock_cards table, searched by stockCardId.
  • query latest PhysicalInventory in physical_inventories table, searched by facilityId.
  • query List of PhysicalInventory in physical_inventories table, searched by facilityId and startDate & endDate of occurreddate.
  • query sum of quantity in stock_card_line_items table, searched by facilityId, orderableIds, startDate & endDate of occurreddate.
  • query List of StockCardLineItem in stock_card_line_items table, searched by stockEventId.
  • update StockCardLineItem with documentnumber in stock_card_line_items table, post body is StockCardLineItem list.

Thanks @yinshangwei,

Could you link to the code you’d like to change the behavior of? And how you’d like it to change. The extension point example like this controller shows how the extension point can be chosen - to be clear this is a basic strategy pattern that you’re likely familiar with, only with some tricks of docker images and containers applied to fit the deployment architecture.

I think the typical pattern is to access stock cards after using /v2/stockCardSummaries. Do you want to query these, or do you think the typical access pattern would be via seeing the stock on hand count first?

Do we need the new field? How would createdtime differ from the associated (via origineventid) stockevent’s processeddate.

Seems reasonable. To be sure we’re on the same page here, the physical inventory table holds draft inventories. I’d have to check if historical inventories are kept. The end state for an inventory is to either be completed and turned into a StockEvent, or deleted.

I think you want /v2/stockCardSummaries here, right?

Stock card line items aren’t really a first-class resource in the API, they’re part of the StockCard resource, so querying them directly might be awkward in the API as-is. Could I ask what you’re looking to achieve?

What do you mean by update the stock card line item? The stock card line item table is append-only. This is by design for accounting/auditing reasons, as well as performance reasons. Could you explain the behavior you’re looking for more here?


I’m going to be hard to get a hold of for the next week. Would you mind mentioning @Klaudia_Palkowska and @Chongsun_Ahn in your response so you may get timely responses.

Thank you all!

Best,
Josh

Thank you @joshzamor.

We want to modify the validation rules of these three validators, such as removing some validations. We know how to use and deploy, we hope the community can add corresponding Extension Point Interface for these three validators so that we can freely modify the logic inside them.
BTW, OrderableFulfillReferenceDataService.java can be removed from the list, as we don’t need to modify it.

We want to get specific orderables from /v2/stockCardSummaries, but currently it does not support to pass orderableids in params.

You are right, the createdtime can not be necessary if the API /api/stockCards/{id} can return createdtime back, that will be OK for us. Our business requirement is to get the createdtime of a Sotck Card.

Historical inventories will be kept and the status of isdraft will be changed from TRUE to FALSE when it turned into a StockEvent.

Sorry, I didn’t explain clearly. This one is to get the sum number of unpacked kits in all programs in a facility during a specific period, so this should be a new API( searched by facilityId, kitIds, startDate & endDate of occurreddate, unpack reasonId).

This used by the update StockCardLineItem API below.

Our business requirement is we can fill a document number for each of stock_card_line_items when we do issue/receive/physical inventory operation. So if community can change POST /api/stockEvents to support we pass document number for each stock_card_line_items, that will be great for us.

Thank you, I’m looping in @Klaudia_Palkowska @Chongsun_Ahn.


Some of the requirements were not written very clearly, I’d like to reorganize our requirements.

About Extension Points:

  • AdjustmentReasonValidator.java
  • FreeTextValidator.java
  • UnpackKitValidator.java

We need to modify or remove some validations according to Mozambique business requirements.

About API Requirements:

  • Get specific orderables(not all orderables in a program, in our case one program can contain more than 1200 products, it will effect our performance) from /v2/stockCardSummaries.
  • Get createdtime of a StockCard from /api/stockCards/{id}.
  • Get latest physicalInventory occurreddate.
  • Get physicalInventories by facilityId and startDate & endDate of occurreddate from GET /api/physicalInventories.
  • Get the sum number of unpacked kits in all programs in a facility during a specific period( searched by facilityId, kitIds, startDate & endDate of occurreddate, unpack reasonId).
  • Update document number of each stock_card_line_items in POST /api/stockEvents, each stock_card_line_item can has different document number.

Please let me know if you have any other questions, thank you.

Hello @yinshangwei

just a quick note/question on the requirement above. It looks like the /v2/stockCardSummaries API already supports querying by (multiple) orderableIds.

Does that not work as expected? Is there a requirement to query by other orderable fields?

Best,
Sebastian

@joshzamor
It seems to me that all of the above API requirements, maybe except for the last one, are globally applicable.They are mainly additions that are backwards compatible, and that could be contributed to the core codebase as a pull request. Would you agree?

As for the last one, I’m not really sure what a document_number is, but I’ve never heard this requirement before. It seems that we could recommned the use of extra_data for that (both Stock Card LI and Stock Card event) and make sure that any extra data from stock events populates the Stock Card Line Items extra data (some refactor may be required in core).

Best,
Sebastian

Hello @Sebastian_Brudzinski

Thank you for your reply. I checked the source code, and YES the /v2/stockCardSummaries API already supports querying by (multiple) orderableIds in StockManagement version rel-5.1.0, but we are using the version rel-5.0.2.
So I think this will be OK when we upgrade to the latest version.