Sourcing Utils
Intended Audience:
Technical User
Authors:
Holger Lierse, Kirill Gaiduk
Changed on:
10 Sept 2026
Overview
The`SourcingUtils` class in the `util-sourcing` bundle is the main utility class that orchestrates the entire sourcing process within a rule. It provides core helper methods such as loading a sourcing profile, initializing the sourcing context, and executing the sourcing logic configured in the profile. Each stage supports multiple customization points. It can also capture a Sourcing Audit of the decision and submit it through the `createSourcingAudit` mutation.Key points
- Main Orchestrator: Central utility class that coordinates all sourcing operations from a rule
- Strategy Evaluation: Evaluates and applies sourcing strategies based on business rules
- Plan Generation: Generates sourcing plans for order fulfillment
- Chunk Loading: Locations are evaluated in incremental chunks to support large sourcing networks. An early availability check skips expensive permutation search when the order cannot be fully sourced from the available stock
- Multi-Attempt Sourcing:
`getPlanFinder`provides a single entry point for primary and fallback sourcing, generating multiple ranked plans without reloading data - Sourcing Auditability: sourcing captures a Sourcing Audit of the decision (strategies, conditions, considered locations and their ratings, and the resulting fulfillments) and submits it with
`captureAudit`
Core Methods
`getPlanFinder()`
The preferred single entry point for running primary or fallback sourcing from the same parameters object. Returns a `SourcingPlanFinder` that exposes:`nextFullPlan()`for primary-strategy sourcing`nextFallbackPlan()`for fallback-strategy sourcing
`findPlanBasedOnStrategies()`
Finds the best sourcing plan for an order based on sourcing strategies defined in a sourcing profile.Location evaluation uses a `ChunkLoadingPlanFinder` that loads locations in incremental chunks sized proportionally to the order's item count. - A single-location search is run after each chunk
- A multi-split search runs across the full evaluated set if no single-location plan is found
- An early availability check is performed before entering permutation search - if any item cannot be covered by the combined quantities across candidate locations, permutation search is skipped
`getBasedOnStrategiesPlanFinder()`
Returns a `SourcingPlanFinder` configured for primary sourcing strategies.`findPlanBasedOnStrategies(SourcingExecutionParameters)` is equivalent to `getBasedOnStrategiesPlanFinder(sourcingExecutionParameters).nextPlan()`.Use this when you need to call `findPlanForAllItems` multiple times without reloading sourcing data from scratch - for example, when generating a ranked list of fulfillment plans.`findPlanBasedOnFallbackStrategies()`
Finds the sourcing plan for unfulfilled items using fallback sourcing strategies when no primary strategy fully satisfies the sourcing request.- Only one fallback strategy is used, specifically the first that satisfies the sourcing conditions
- Supports partial sourcing, where fulfillments may not completely satisfy the order
- Location ratings are recalculated after each allocation iteration using remaining unfulfilled items, ensuring each location selection reflects actual demand at that point in the iteration
`getBasedOnFallbackStrategiesPlanFinder()`
Returns a `SourcingPlanFinder` configured for fallback sourcing strategies.`findPlanBasedOnFallbackStrategies(SourcingExecutionParameters)` is equivalent to `getBasedOnFallbackStrategiesPlanFinder(sourcingExecutionParameters).nextPlan()`.Wrap the returned finder (for example, for multi-attempt location exclusion) before calling `findPartialFulfilmentPlan` in a loop.`buildRejectedFulfilment()`
Builds a rejected fulfillment for all remaining unfulfilled items in the sourcing context.`captureAudit()`
Submits the completed Sourcing Audit at the end of a Sourcing Request. Call it after Fulfillments are created: it stamps the applied Sourcing Profile onto the plan's audit and queues the `createSourcingAudit` mutation.Pass the `sourcingContext` so the audit is recorded against the sourced entity, for example it supplies the Fulfillment Choice id and reference stored on the audit.When building a custom rule with the utilities, enable capture by supplying a `DefaultSourcingAuditRecorder` through `SourcingExecutionParameters.auditRecorder(...)`; when no recorder is supplied the call is a no-op.`DefaultSourcingAuditRecorder`captures the decision during plan-finding and posts the audit. Create a new instance per rule invocation; it is stateful, so never share it across rules or store it on a rule field`NoOpSourcingAuditRecorder`is the default when`auditRecorder`is not set. It ignores every capture call, so an un-instrumented sourcing path pays no cost
Supporting Methods
`findPlanForAllItems()`
This helper method is used by the `findPlanBasedOnStrategies` method to identify a plan for an order based on the sourcing strategies. It ranks candidate locations using the provided sourcing criteria, and searches for the best combination of locations that can cover the full order within the allowed split limit. Fewer-location plans are always preferred.Before entering permutation search, an early availability check sums available quantities for each required item across all candidate locations. If any item cannot be covered, permutation search is skipped. If no valid combination exists, it returns an empty plan.`findHighestValuePartialFulfilment()`
This helper method is used by the `findPlanBasedOnFallbackStrategies` method to find the highest-value partial fulfillment. It filters out excluded locations, compares each candidate's rating based on the remaining unfulfilled items at that iteration, and checks whether the location can cover at least part of the remaining items. The method returns the best fulfillment found or none if no positive-value option exists.`findPartialFulfilmentPlan()`
Builds a greedy partial fulfillment plan by repeatedly calling `findHighestValuePartialFulfilment` until the `maxSplit` limit is reached or all unfulfilled items are covered. Location ratings are recalculated after each allocation iteration.Use `getBasedOnFallbackStrategiesPlanFinder` to obtain a pre-loaded `SourcingPlanFinder`, then wrap it (for example, for multi-attempt location exclusion) before calling `findPartialFulfilmentPlan` in a loop.`loadPositions()`
Loads virtual positions for sourcing operations. This method is used by both core methods (`findPlanForAllItems` and `findPlanBasedOnFallbackStrategies`) to load inventory.`loadSourcingProfile()`
Loads the sourcing profile for the current context.`getUnfulfilledItems()`
Computes outstanding order items after accounting for allocated but non-rejected quantities.`getNetworkRef()`
Gets the network reference from a sourcing profile or strategy.`getVirtualCatalogueRef()`
Gets the virtual catalog reference from a sourcing profile or strategy.`getMaxSplit()`
Gets the maximum split value from a sourcing profile or strategy.`getSourcingPlanAudit()`
Returns the `SourcingPlanAudit` attached to a plan. It is always non-null and carries the full decision: the overall status (`FULLY_SOURCED`, `PARTIALLY_SOURCED`, or `NOT_SOURCED`), the sourcing type (`PRIMARY` or `FALLBACK`), the evaluated strategies, the applied Sourcing Profile, the requested Items, and the considered location count.