Design Requisition Line Item use of Orderable/FTAP versioning

Hi everyone,

I’m currently designing an architecture of using Orderable and FTAP versioning in Requisition Line Item (RLI). I have figured out the following changes which should be committed in RLI:

  1. Adding FTAP id and FTAP version to RLI - to reference an FTAP in RLI to handle multiple version
  2. Adding Orderable version to RLI - to reference an Orderable in RLI to handle multiple version. Orderable id has been already added.
  3. Removing maxPeriodsOfStack from RLI entity - this field is currently snapshotted (copied) from FTAP. After adding a reference to FTAP, the FTAP fields shouldn’t be stored in RLI but retrieved from FTAP on demand.
  4. Removing packsToShip, pricePerPack, totalCost and nonFullSuply from RLI entity - the fields are currently snapshotted (fetched from Orderable and calculated). The values should be retrieved via Orderable reference.
  5. Id and version should be encapsulated in one class eg. EntityReference. It should apply both to Orderable and FTAP reference.

There should be a migration committed for the existing RequisitionLineItems. The simplest approach is to drop the mentioned fields and obtain the values by referencing the latest available Orderable/FTAP version.

What do you think about the described solution? Do you have any suggestions or do you see any potential impediments?

1 Like

Thanks Paweł, this sounds good to me.

Similar to what Klaudia stated in her post, we will need to review and see what work is needed in the requisitions reports (I’m thinking about requisition print - do we have any other?). The reports should also use versioned orderables.

It’s worth noting that this will require a cross-service migration (we need data both from requisitions and referencedata). Using latest orderable/FTAP version is a big assumption, but since the requisition service never fully supported updating products, I think this is fine - we will need to document this in the release notes for sure though.

Best,
Sebastian

Thank you Sebastian for your reply.

I have found only one requisition report which uses orderable fields - RequisitionLines.jrxml (link). In contrast to Proof of Delivery report we do not use SQL query there. Orderables are retrieved by the service on the backend, so if we committed the changes to the RequisitionLineItem and related classes, the report should have access to orderable’s fields automatically.

However, we plan to remove some parameters (eg. pricePerPack) so there will be a need to replace these fields with the proper methods which use up-to-date orderable state (eg. calculatePricePerPack()).

Best,

Thanks @pcieszko, and I agree with @Sebastian_Brudzinski.

I’d highlight two more things that might be effected by this breaking change:

  • the reporting flows in Nifi
  • the OpenSRP integration

Since this is a breaking API change to Requisitions I’m wondering if we might want to continue getting used to staging the change: make all the changes on our side and switch over, but keep the snapshotted information in the API response for a release cycle or two. Or we could version GET Requisition like we did with /api/v2/stockCardSummaries (i.e. add a new resource under /api/v2). Either way it’d be good to keep practicing the habit of limiting our breaking API changes and giving grace periods for external systems.

Thoughts?

Best,
Josh

Thanks @joshzamor for your remarks.

We think about adding the separated endpoints (/v2/) with the newest form of RequisitionLineItem. However, the previous form would be also supported. We’d like to implement /v2/ version step by step (starting at UI). This approach will let us avoid compatibility issues and that’s why we don’t need to worry about NiFi and OpenSRP so far. Nevertheless, the main disadvantage is that we will need to maintain more endpoints in code.

The following endpoints for “/requisitions” will be implemented in /v2/ form, because the planned changes in RequisitionLineItem would affect them:

  • BatchRequisitionController - retrieveAll, updateAll, saveAll
  • RequisitionController - initiate, updateRequisition, getRequisition, getSubmittedRequisitions

To sum up, seven new /v2/ endpoints will be created.

Best,
Paweł

Seven more endpoints is quite a number to maintain. I wonder if we need to do this for batch endpoints. Our UI is most likely the only consumer of those endpoints, so maybe we could only maintain v1 and v2 of endpoints you mentioned under RequisitionController?

Best,
Sebastian