Sourcing Utils
Intended Audience:
Technical User
Author:
Holger Lierse
Changed on:
22 Sept 2025
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, initialise the Sourcing Context, and trigger the execution of the sourcing logic configured in the profile. Each stage supports multiple customisation points throughout the process.
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: Creates optimal sourcing plans for order fulfillment
Core Methods
`findPlanBasedOnStrategies()`
Finds the best Sourcing Plan for an order based on sourcing strategies defined in a Sourcing Profile.
1SourcingPlan plan = SourcingUtils.findPlanBasedOnStrategies(
2 context,
3 sourcingContext,
4 profile,
5 ImmutableList.of(Constants.Status.ACTIVE),
6 null // No custom inventory processor
7);`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.
- Usually considers customer value over cost savings
1SourcingPlan plan = SourcingUtils.findPlanBasedOnFallbackStrategies(
2 context,
3 sourcingContext,
4 profile,
5 ImmutableList.of(Constants.Status.ACTIVE),
6 null // No custom inventory processor
7);
8 `buildRejectedFulfilment()`
Builds a rejected fulfillment for all remaining unfulfilled items in the sourcing context.
1// Build system rejected fulfillment for unfulfillable items
2Fulfilment rejectedFulfilment = SourcingUtils.buildRejectedFulfilment(
3 context,
4 sourcingContext,
5 context.getProp(PROP_SYSTEM_REJECTED_LOC_REF)
6);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 loads candidate locations and their stock positions, ranks them 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. If no valid combination exists, it returns an empty plan.
1// Load virtual positions
2List<LocationAndPositions> locationAndPositions = SourcingUtils.loadPositions(
3 context,
4 sourcingContext,
5 sourcingProfile,
6 strategy,
7 ImmutableList.of(Constants.Status.ACTIVE)
8);
9
10// Get strategy configuration
11String networkRef = SourcingUtils.getNetworkRef(sourcingProfile, strategy);
12String virtualCatalogueRef = SourcingUtils.getVirtualCatalogueRef(sourcingProfile, strategy);
13Integer maxSplit = SourcingUtils.getMaxSplit(sourcingProfile, strategy);
14
15// Generate sourcing plan
16SourcingPlan plan = SourcingUtils.findPlanForAllItems(
17 context,
18 sourcingContext,
19 locationAndPositions,
20 maxSplit,
21 null // Use default scoring
22);`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, 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.
1Set<String> excludedLocations = Set.of("warehouse-001", "store-002");
2Optional<Fulfilment> partialFulfilmentOpt = SourcingUtils.findHighestValuePartialFulfilment(
3 locationAndPositions,
4 unfulfilledItems,
5 excludedLocations
6);
7
8if (partialFulfilmentOpt.isPresent()) {
9 Fulfilment partialFulfilment = partialFulfilmentOpt.get();
10
11 // Calculate remaining items after partial fulfillment
12 List<OrderItem> remainingItems = OrderUtils.itemsMinusFulfilments(
13 unfulfilledItems,
14 Arrays.asList(partialFulfilment)
15 );
16
17 // Create the partial fulfillment
18 OrderUtils.fillFulfilmentType(sourcingContext, Arrays.asList(partialFulfilment));
19 OrderUtils.createFulfilments(context, sourcingContext, Arrays.asList(partialFulfilment));
20
21 context.action().log("Created partial fulfillment with {} items",
22 partialFulfilment.getItems().size());
23}`loadPositions()`
Loads Virtual Positions for sourcing operations. This method is used by both core methods (`findPlanForAllItems` and `findPlanBasedOnFallbackStrategies`) to load inventory.
1List<LocationAndPositions> locationAndPositions = SourcingUtils.loadPositions(
2 context,
3 sourcingContext,
4 sourcingProfile,
5 sourcingStrategy,
6 ImmutableList.of(Constants.Status.ACTIVE)
7);`loadSourcingProfile()`
Loads the sourcing profile for the current context.
1SourcingProfile profile = SourcingUtils.loadSourcingProfile(context);
2
3if (profile != null) {
4 // Use the profile for sourcing operations
5 SourcingPlan plan = SourcingUtils.findPlanBasedOnStrategies(
6 context,
7 sourcingContext,
8 profile,
9 ImmutableList.of(Constants.Status.ACTIVE),
10 null
11 );
12}`getUnfulfilledItems()`
Computes outstanding order items after accounting for allocated but non-rejected quantities.
1List<OrderItem> unfulfilledItems = SourcingUtils.getUnfulfilledItems(context);`getNetworkRef()`
Gets the network reference from a Sourcing Profile or Strategy.
1String networkRef = SourcingUtils.getNetworkRef(profile, strategy);`getVirtualCatalogueRef()`
Gets the Virtual Catalog reference from a Sourcing Profile or Strategy.
1String catalogueRef = SourcingUtils.getVirtualCatalogueRef(profile, strategy);`getMaxSplit()`
Gets the maximum split value from a Sourcing Profile or Strategy.
1Integer maxSplit = SourcingUtils.getMaxSplit(profile, strategy);
