Central Ordering For a Consortium

This page will document the design to central ordering within a ECS(Enhanced Consortia Support) enabled system.

 

Configuration

There will be a new setting that will enable central ordering or network ordering. When the setting is enabled, new behavior described in this document will take hold. This setting will live in mod-orders-storage and editable in ui-orders via the the Settings UI

Might need to change name of setting to Joint Ordering

Locations

It is a requirement of central ordering that locations from all tenants in the consortium is available for library staff. Appropriate permissions have to be granted to access the locations of member tenant.

There is no need for additional facilities to have a consolidated list of locations in the consortium. The user experience dictated by the requirements proposes to select an affiliation first before selecting a location within the affiliation. This means that the UI will get the list of locations for each selected affiliation.

To accomplish this feature, it will be possible to link locations in other tenants than the tenant that owns the Order. Specifically, tenantId will be added to each schema of the object contained in the locations array property of Purchase Order Lines. Together with the location identifier, further processing can select the right location in right tenant.

UI

With the possibility of multiple Holdings existing in multiple tenants, showing details of a location will require multiple calls to different tenants based on the owning tenant of each Location. The UI should display the page without waiting on all results. If is prioritized for the Ramsons release, mod-search could be used to retrieve all Locations in one call.

Ordering

The schema of the Piece object will be updated to include receivingTenantId. receivingTenantId will be used to denote the tenant where the piece will be received. The Piece object will still live in central tenant.

When an Order is opened, and inventory objects need to be created, they will be created at the data tenant specified by the location in the Purchase Order Line. The location will have a tenant identifier to help select the tenant.

When an instance connection change happens, Inventory objects will be recreated in the appropriate tenants.

UI

When an order line is being created, a lookup is performed to see if the order line is a duplicate. The current query searches for holdings for the particular instance. In ECS, holdings do not live in the central tenant. When central ordering is enabled, mod-search is queried to get all holdings across a consortium to determine duplicates

 

Receiving

UI

Upon initialization of the home page of the Receiving app, a user will be able to choose to view central orders only or local orders only. Depending on the user selection, a request may be sent to the current affiliation of the user or to the central tenant. The option to select central or local orders will be dependent on central ordering setting being enabled.

When viewing a central order, pieces belonging to other affiliations should not be visible. Pieces belonging to the current affiliation is important to the library staff.

A new facet/UI control is needed in the left navigation pane that will show central orders only or local orders only.

It should be possible to edit a piece in the central tenant while still in a active affiliation that is not the central tenant.

Inventory

Purchase Order Line information in Inventory will be populated as is to limit breaking changes. This means that Inventory Items might reference Purchase Order Lines that are not in the current tenant. Clients of this information can be modified to query the central tenant of a consortium for the existence of the Purchase Order Line. The identifier of the central tenant of a consortium setup should be globally available to all FOLIO modules via facilities provided by mod-consortia.

UI

Upon initialization of a Instance detail page in Inventory, two queries will be sent to the current affiliation tenant and the central tenant to populate the acquisitions accordion of the Instance detail page. The second query to the central tenant will only be sent if central ordering is enabled for the consortium.

On the Item detail page, acquisition information is derived from the purchaseOrderLineIdentifier property of the Item. We will take this opportunity to further decouple Inventory from Acquisitions. Acquisitions will have a dependency on Inventory but not vice versa. The UI will query acquisitions with the Item id to retrieve the Purchase Order Line information, this is referenced here. This should occur even with central ordering disabled i.e. non-ECS functionality as well.

Relationship Between Purchase Order Line(POL) and Inventory Item

Today, purchase order line information is stored in Item objects in Inventory. We need to stop promoting its use and offer a different path to the same information.

In mod-orders there will be a new relationship table between purchase order line and an Inventory item. The table will help support the following query with similar parameters

GET /orders/order-lines?limit=1000&query=inventoryItemId==8ae07ded-7ad2-49a2-a701-485ce7a3e898 HTTP/1.1

The result of the query above should be only one order line even though the response is a collection of purchase order lines. The same order line would have been surfaced by purchaseOrderLineIdentifier on the item object.

The relationship table should be populated whenever puchaseOrderLineIdentifier on the Item object is populated. It should contain the following columns

  • inventoryItemId - Inventory Item identifier, Primary key

  • inventoryItemTenantId - Tenant identifier of the Inventory Item, Primary key

  • poLineid - Purchase Order Line identifier

  • created_by

  • creation_date

The full Purchase Order Line object will be returned in the response.

Migration

Upon initialization of the new module version, relationship table for POL and Item will be empty. An async migration will begin that will query Inventory Items(purchaseOrderLineIdentifier is not null) and save appropriate record in the relationship table.

In addition, when the relationship table is queried and no objects are found, an HTTP call to inventory is made a fallback. If there is no appropriate item in Inventory, a row in the relationship table is created with the purchase order identifier column as empty. If there is an appropriate item in Inventory, the purchase order identifier column will be populated. Other columns on the table will be populated as normal. This fallback HTTP call will be deprecated in a future release.

 

Q&A

Question

Refs

Answer

Fully answered

Who answered

Question

Refs

Answer

Fully answered

Who answered

What is the expected behavior when switching “Allow user to select locations from other affiliations for central orders” setting to "false" mode and having assigned locations from member tenants in the Purchase Order Line and/or Fund? (Will the associations remain in the member tenants after disabling the configuration?)
сс. @Dennis Bridges

For the R release we will prevent users from being able to deactivate this setting.

When user checks this box in settings the system must present a confirmation modal. Message: “In this version of FOLIO, once activated this setting cannot be disabled. Are you sure you would like to activate this functionality.”

No

Dennis B

Should the location "Name (code)" (or "Holding") field be cleared when changing the value of the "Affiliation" field in the PO Line or Piece form?
cc @Dennis Bridges

TODO: create related UIREC story to populate affiliation field in the piece form

Yes the second field should be cleared when affiliation is changed.

Yes

Dennis B

Can a user who is not affiliated with a specific tenant delete location lines from those tenants in the PO Line form?
cc @Dennis Bridges

Yes if user has ability to edit POL they should be able to edit location fields. However, if they remove an affiliation they do not have they will not be able to add it back. They would need to cancel their edit to undo that change.

Yes

Dennis B