| Author | Olamide Kolawole/Serhii Nosko |
|---|---|
| JIRA task | Folijet: UXPROD-185 - Getting issue details... STATUS Thunderjet Support: TBD |
| Business Requirements | |
| Architects Review | IN PROGRESS |
| PO review | IN PROGRESS |
Revision History
| Version | Date | Owner | Description | Reason |
|---|---|---|---|---|
| v1.0 | 06.26.2022 | Initial version | ||
| v1.1 | 06.28.2022 | Add model schemas | ||
| v1.2 | 06.30.2022 | Add diagrams for Inventory creation | ||
| v1.3 | 06.30.2022 | Add diagrams for creating and opening orders | ||
| v1.4 | 07.07.2022 | Formatting changes |
Overview
This document will illustrate the design that will integrate the Orders module area with Data Import(DI) module area. Order lines will be defined in MARC Bibliographic(MARC Bib) files by a user. The MARC Bib files will be parsed by DI and have records sent to mod-orders via Kafka eventing.
Solution Design
Architectural Requirements
- Dependency Inversion: Unlike traditional integrations that have been implemented with Inventory and less so with Invoices, Orders will be a consumer of Data Import. Data Import will be responsible for parsing input files from a user into a form that FOLIO modules will understand to Create/Update their respective objects.
- Single Source of Truth: This design should ensure that business logic only lives in one location within the FOLIO system. Orders and Data Import should not have copies/variants of the same functionality. This will reduce maintenance issues, clearly designate responsibilities and reduce cognitive load when developing the Orders and Data Import sub-systems.
- Clearly Defined Input & Outputs of Components: Each component in the process flow should have clearly defined inputs and outputs. The cardinality of inputs and outputs of each component should be generally less than three. If the cardinality is more than three, then division of the component should be considered.
Process Flows
Create Inventory Instance, Holdings, Item Within Order Create/Update
The basic question here, do we need to create Instance, Holdings, Item by DI in mod-inventory using full power of MARC file and Order mapping profile to map Instance, Holdings, Item, or use standard mapping capabilities provided by mod-orders. The screenshot below is of the Orders UI showing where the "Create Inventory" action is selected.
Below is an enumeration of two approaches that could be used to support creation of Inventory objects for Orders.
Approach #1 with creating Inventory instance, holdings, item in mod-inventory by DI
Benefits of this approach:
- Inventory Instance, Holdings, Item can be mapped separately from mod-orders. In this case Orders field mapping profile can be adjusted with new Inventory field to map easily. Mod-orders creates Inventory from predefined set of fields from template on Create Orders UI and does not satisfy powerful mapping capabilities, that possible if mapping from the marc file
- Instance create post processing logic invoked in the same manner as in common DI flow to connect Inventory instance with source marc record
Drawbacks of this approach:
- More amount of work needed to create Inventory instance, holding, item, because not using approach from the box when mod-orders create these entities automatically during openning of the order
- New story for mod-orders needed to support new parameter: inventoryFlow with allowed values[Synchronized, Independent]. In this approach this param value should be set to Independent
Creating of Inventory Instance, Holdings, Item from Order basically is optional step, it's possible the library is ordering something that they do not want represented in Inventory (like a database that they maybe want to handle through the ERM app), or other random things that they do not plan to keep in their permanent collection.
The diagram below shows scenario when user chooses to create Instance and/or Holdings and/or Item on the Orders field mapping profile.
The diagram below shows a scenario where users chooses to NOT create Instance and/or Holdings and/or Item on the Orders field mapping profile.
Since for order mapping we use single mapping profile - we don't need separate topics for each Inventory type. So when DI_SRS_MARC_BIB_RECORD_CREATED event comes, data-import-processing-core will chose new CreateOrdersInventoryDataHandler based on action profile Create Orders.
CreateOrdersInventoryDataHandler will invoke Inventory Storage REST APIs to create Instance, Holdings, Item one by one based on Orders mapping profile configuration
Sequence diagram can be edited using this tool: https://www.planttext.com/
Link to the standard flow of creating Instance, Holdings, Item in DI: 1. Create MARC Bib, create Instance, Holdings, Item
Approach #2 with creating Inventory instance, holdings, item in mod-inventory by mod-orders
Create Pending VS Open Order
User selects 'Create order' in Order mapping profile
User selects 'Create and open order' in Order mapping profile
In this diagram assuming that aproach to create Inventory from mod-orders service chosen and user selects Create Instance, Holdings, Item from Order mapping profile
Data Model
Purchase Order
Required fields
| Field name | Allowed values | Description |
|---|---|---|
| orderType | [One-Time, Ongoing] | DI will setup only One-Time order type |
| vendor | - | Vendor that user chooses on Order field mapping profile |
Not applicable fields for DI orders flow
Business requirements to answer why provided fields are not necessary to populated
Business Requirements
- Use for one-time orders (physical, electronic, or both). Do not use for ongoing or package orders
- Should field mapping profiles use order templates?
- No. The field mapping profile and its mapped/default data already acts as a template. Once a field mapping profile is set up, it does not have to be re-created each time a user imports
- Can it create/assign order notes?
- No. Not the order notes created in the separate notes app
- Can it create/assign tags?
- No, not yet, for any record type. Aiming to support tags in a future version of DI
| Field name | Allowed values | Description |
|---|---|---|
| reEncumber | [True, False] | Indicates this purchase order should be re-encumbered each fiscal year |
| needReEncumber | [True, False] | Indicates that order needs to be re-encumbered |
| ongoing | - | Ongoing object includes these fields: interval, isSubscription, manualRenewal, notes, reviewPeriod, renewalDate, reviewDate All these fields should not be populated from DI, because DI does not support ongoing orders. |
| template | - | Predefined template to create order from |
| notes | - | Free-form notes associated with this purchase order |
| tags | - | List of simple tags that can be added to the purchase order |
Composite Purchase Order Lines
Required Fields
| Field name | Allowed values | Description |
|---|---|---|
| acquisitionMethod | - | The UUID format string |
| cost | - | The purchase order line cost. Includes fields: "listUnitPrice", "listUnitPriceElectronic", "currency", "additionalCost", "discount", "discountType", "exchangeRate", "quantityPhysical", "quantityElectronic", "poLineEstimatedPrice", "fyroAdjustmentAmount" Currency field is required. |
| orderFormat | [Electronic Resource, P/E Mix, Physical Resource, Other] | The purchase order line format |
| source | [User, API, EDI, MARC, EBSCONET] | The source of the order |
| titleOrPackage | - | The title of the materials |
Not applicable fields for DI orders flow
Business requirements to answer why provided fields do not necessary to populate
Requirements from business
Use for one-time orders (physical, electronic, or both). Do not use for ongoing or package orders
| Field name | Allowed values | Description |
|---|---|---|
| isPackage | [True, False] | Indicates that this POL is for a package. Default - false |
| packagePoLineId | - | Specify package po line id, applicable only package orders |
| renewalNote | - | Specify renewal note, applicable only for ongoing orders |
Mapping Instance, Holdings, Item in mod-orders
How to disable creating Instance, Holdings, Item in mod-orders (todo need to verify)
Disabling of creating Inventory records for physical resource
This schema represents a field 'physical' of Purchase Order line in order. To disable creating Inventory records need to set createInventory field to 'None'
Disabling of creating Inventory records for electronic resource
This schema represents a field 'eresource' of PO line in order. To disable creating Inventory records need to set createInventory field to 'None'
APIs
DI will communicate with mod-orders using kafka messaging, the same approach used for Inventory and Invoice module areas
Business Requirements
- Should orders be created as pending or open?
- Use cases for both, so include required field at top of field mapping profile that allows the user to set the status
Create orders
Applies when user choses to create pending order on the field mapping profile screen.
There is field in compositePurchaseOrder request payload named workflowStatus, it will be PENDING by default.
For creating orders CreateOrderEventHandler will use the same implementation as corresponding endpoint uses.
| Method | Url | Request parameters | Request payload | Description |
|---|---|---|---|---|
| POST | /orders/composite-orders | lang | compositePurchaseOrder | Post a purchase order (PO) and a number of PO lines; record fund transactions corresponding to the order. Only in case an acquisition unit has to be assigned to |
Open orders
Applies when user choses to create open order on the field mapping profile screen.
There is field in compositePurchaseOrder request payload named workflowStatus, it should be set as OPEN.
For creating orders CreateOrderEventHandler will use the same implementation as corresponding endpoint uses.
| Method | Url | Request parameters | Request payload | Description |
|---|---|---|---|---|
| POST | /orders/composite-orders | lang | compositePurchaseOrder | Post a purchase order (PO) and a number of PO lines; record fund transactions corresponding to the order. Only in case an acquisition unit has to be assigned to |
Receive orders
Work Breakdown Structure
Open Items
| Question | Status | Answer |
|---|---|---|
| Oder payload has field 'approved', that is false by default. What value for this field DI should populate? | IN PROCESS | Ann-Marie Breaux (Deactivated) will discuss with SMEs. |
| When we have situation that max order lines limit is 10, but have 15 order lines and 2 orders in marc file, how they should be mapped? | IN PROCESS | Ann-Marie Breaux (Deactivated) will discuss with SMEs. |
| PO number can be auto generated by mod-orders system. Does it necessary to place this field on Order mapping profile? | IN PROCESS | Ann-Marie Breaux (Deactivated) will discuss with SMEs. |
| When creating order lines - its necessary to specify order source from these allowed values: [User, API, EDI, MARC, EBSCONET]. For our case it should be MARC? | CLOSED | MARC value should be used. |
| Do we need to support orders check-in after receiving? | CLOSED | Updated after conversation with Thunderjet Actually, checking and receive is the same thing, DI should use checking endpoint implementation |
| Is it possible scenario when DI going to open order, but not create any Instance, Holdings. Item? | CLOSED | Yes, it's possible the library is ordering something that they do not want represented in Inventory (like a database that they maybe want to handle through the ERM app), or other random things that they do not plan to keep in their permanent collection. |
Open items to brainstorm with SA, Devs
| Question | Status | Answer |
|---|---|---|
We use database tables for DI handlers deduplication. Mod-orders does not have schema in DB and any DB related code. Do we need to follow the same approach with introducing schema as we did in mod-inventory | OPEN | |
If we are going to create Inventory Instance, Holdings, Item separately - need to discuss with Thunderjet possibility to indroduce new order parameter inventoryFlow with allowed values: [Synchronized, Independent], the same as did in Order Receiving flow | OPEN |
Created stories
| Description | Module | Story |
|---|---|---|
| Create default order mapping profile | data-import-converter-storage | TBD |
Extend mapping engine with ability to create order and multiple order lines from the same MARC record. | data-import-processing-core | TBD |
| Adjust mod-orders to validate purchase order lines limit from Orders mapping profile | ||
| Add kafka handlers in mod-orders | mod-orders | TBD |
| Adjust mod-orders order lines limit validation to support fetching this param from DI Orders mapping profile | mod-orders | TBD |