How Sourcing Utilities work

Topic

Author:

Holger Lierse

Changed on:

7 July 2026

Overview

The articles below will walk you through the Sourcing Utilities (`util-sourcing`), designed to simplify implementing complex sourcing logic and reduce repetitive code.PrerequisitesBefore diving in, make sure you have:

A basic understanding of the Utility Bundles and Sourcing Utilities
Familiarity with writing Rules using the Rules SDK
Completed the Getting Started with the Utility Bundles guide

Author:

Holger Lierse

Changed on:

7 July 2026

Overview

The `util-sourcing` library is a comprehensive collection of utility functions designed to minimize the overhead and complexity of writing sourcing logic in your Fluent Commerce rules.PrerequisitesThese articles assumes you're familiar with:

Java
Maven
JUnit

Key points

Sourcing Orchestration (`SourcingUtils`): Orchestrates the sourcing process and provides helper methods to load a Sourcing Profile
Context Management (`SourcingContextUtils`): Loads and manages Sourcing Context
Order Helper (`OrderUtils`): Performs order-specific operations such as fulfillment creation
Location-Based Optimization (`LocationUtils`): Provides location-based helpers including distance calculations and caching
Fulfillment Options Support (`FulfilmentOptionsUtils`): Creates fulfillment plans with available quantity tracking and ETA calculation
Sourcing Conditions and Criteria Management: Provides functions, registration, and execution logic for tailoring Sourcing Strategies to the specific needs of customers

Java Docs

The helper methods contained in the Utility Bundles libraries are many and varied, so the JavaDocs provided with the packages should be treated as the source of truth for documentation.

Value Proposition

Eliminate Manual Sourcing: Pre-built utility methods handle complex inventory allocation and location selection logic
Faster Implementation: Common sourcing patterns are abstracted into reusable, tested components
Reduced Complexity: Standardized approaches prevent common sourcing errors and edge cases
Extensibility: Custom sourcing strategies can be easily implemented.
Consistent Patterns: Enforce best practices across your sourcing rule implementations

Explanation through an Example

Let's walk through a simple real-world scenario to understand how Sourcing Utilities work in practice.Imagine you're running an online store that receives an order for:

2x Gaming Laptops (high-value items)
3x Wireless Mice (medium-value items)
1x Gaming Headset (high-value item)

The customer lives in New York City, and you have inventory at multiple locations:

Main Warehouse (New Jersey) - Has all items in stock
Local Store (Manhattan) - Has laptops and mice, but no headset
Regional DC (Boston) - Has all items but higher shipping costs

How Sourcing Utilities Help

1// Load the sourcing profile for the current context
2SourcingProfile sourcingProfile = SourcingUtils.loadSourcingProfile(context);

Language: java

Name: Load the Sourcing Profile

Description:

Profile can contain Conditions and Strategies like:
- "Peak period" (only apply the strategy during peak period)
- "Bulky items" (only apply the strategy for orders which contain bulky items)
- "Proximity First" (prioritize closest locations)
- "Cost Optimized" (minimize total fulfillment cost)
- "Speed Priority" (fastest delivery regardless of cost)Please note that the Rule property referencing the Sourcing Profile is assumed to be name `sourcingProfileRef`.

1// Create sourcing context with unfulfilled order items
2SourcingContext sourcingContext = SourcingContextUtils.loadSourcingContext(
3    context, 
4    SourcingUtils::getUnfulfilledItems
5);

1// Find the best sourcing plan based on strategies
2SourcingPlan plan = SourcingUtils.findPlanBasedOnStrategies(
3    context,
4    sourcingContext,
5    sourcingProfile,
6    ImmutableList.of(Constants.Status.ACTIVE),  // Consider only ACTIVE positions
7    this::customInventoryProcessor
8);

1// The system generates a sourcing plan that might look like:
2SourcingPlan optimalPlan = new SourcingPlan();
3optimalPlan.addFulfilment(
4        SourcingUtils.Fulfilment.builder()
5                .location(Location.builder().name("Manhattan Store").build())
6                .items(Arrays.asList(
7                        Fulfilment.FulfilmentItem.builder().ref("2x Laptops").build(),
8                        Fulfilment.FulfilmentItem.builder().ref("3x Mice").build())
9                )
10                .build()
11);
12optimalPlan.addFulfilment(
13        SourcingUtils.Fulfilment.builder()
14                .location(Location.builder().name("NJ Warehouse").build())
15                .items(Arrays.asList(
16                        Fulfilment.FulfilmentItem.builder().ref("3x Mice").build())
17                )
18                .build()
19);

1// Set fulfillment types
2OrderUtils.fillFulfilmentType(sourcingContext, fulfilments);
3
4// Create fulfillments from the plan
5List<Fulfilment> fulfilments = OrderUtils.createFulfilments(
6    context, 
7    sourcingContext, 
8    plan.getFulfilments()
9);

What Happens Behind the Scenes

Inventory Analysis: System checks real-time inventory at all locations
Distance Calculation: Calculates delivery times and costs for each location
Strategy Evaluation: Applies business rules (proximity, cost, speed)
Optimization: Finds the best combination of locations to fulfil the order

This example shows how Sourcing Utilities transform a complex business decision into simple code.

Overview

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

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

The underlying finder for each variant is initialized lazily on the first call and reused on subsequent calls, so sourcing data is loaded at most once per variant.

1SourcingExecutionParameters params = SourcingExecutionParameters.builder()
2        .context(context)
3        .sourcingContext(sourcingContext)
4        .profile(sourcingProfile)
5        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
6        .build();
7
8SourcingPlanFinder finder = SourcingUtils.getPlanFinder(params);
9
10// Primary sourcing: call multiple times to produce alternative
11// plans without reloading sourcing data
12SourcingPlan plan = finder.nextFullPlan();
13
14// Fallback sourcing from the same parameters object
15SourcingPlan fallbackPlan = finder.nextFallbackPlan();

Decorator Scenario

To wrap the finder in a decorator (for example, location exclusion between attempts), use `getBasedOnStrategiesPlanFinder` or `getBasedOnFallbackStrategiesPlanFinder` directly and wrap the returned finder before calling `nextPlan()`.

`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

1SourcingPlan plan = SourcingUtils.findPlanBasedOnStrategies(
2    SourcingExecutionParameters.builder()
3        .context(context)
4        .sourcingContext(sourcingContext)
5        .profile(profile)
6        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
7        .build()
8);

`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.

1SourcingPlanFinder planFinder = SourcingUtils.getBasedOnStrategiesPlanFinder(
2    SourcingExecutionParameters.builder()
3        .context(context)
4        .sourcingContext(sourcingContext)
5        .profile(profile)
6        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
7        .build()
8);
9// Call nextPlan() for each attempt without reloading sourcing data
10SourcingPlan plan = planFinder.nextPlan();

`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

1SourcingPlan plan = SourcingUtils.findPlanBasedOnFallbackStrategies(
2    SourcingExecutionParameters.builder()
3        .context(context)
4        .sourcingContext(sourcingContext)
5        .profile(profile)
6        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
7        .build()
8);

`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.

1SourcingPlanFinder fallbackFinder = SourcingUtils.getBasedOnFallbackStrategiesPlanFinder(
2    SourcingExecutionParameters.builder()
3        .context(context)
4        .sourcingContext(sourcingContext)
5        .profile(profile)
6        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
7        .build()
8);
9// Wrap finder for multi-attempt location exclusion, then call nextPlan()
10SourcingPlan partialPlan = fallbackFinder.nextPlan();

`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 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.

1String networkRef = SourcingUtils.getNetworkRef(sourcingProfile, strategy);
2String virtualCatalogueRef = SourcingUtils.getVirtualCatalogueRef(sourcingProfile, strategy);
3Integer maxSplit = SourcingUtils.getMaxSplit(sourcingProfile, strategy);
4List<Location> locations = LocationUtils.getLocationsInNetwork(context, networkRef);
5
6SourcingPlan plan = SourcingUtils.findPlanForAllItems(
7    SourcingExecutionParameters.builder()
8        .context(context)
9        .sourcingContext(sourcingContext)
10        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
11        .build(),
12    virtualCatalogueRef,
13    locations,
14    sourcingCriteria,
15    maxSplit
16);

`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.

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}

`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.

1SourcingPlanFinder fallbackFinder = SourcingUtils.getBasedOnFallbackStrategiesPlanFinder(
2    SourcingExecutionParameters.builder()
3        .context(context)
4        .sourcingContext(sourcingContext)
5        .profile(profile)
6        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
7        .build()
8);
9SourcingPlan partialPlan = SourcingUtils.findPartialFulfilmentPlan(
10    sourcingContext,
11    fallbackStrategy,
12    unfulfilledItems,
13    locationsWithPositions,
14    criteria,
15    locationLimit,
16    maxSplit
17);

`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    SourcingExecutionParameters.builder()
3        .context(context)
4        .sourcingContext(sourcingContext)
5        .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
6        .build(),
7    sourcingCriteria,
8    virtualCatalogueRef,
9    locations
10);

`loadSourcingProfile()`

Loads the sourcing profile for the current context.

1SourcingProfile profile = SourcingUtils.loadSourcingProfile(context);
2if (profile != null) {
3    SourcingPlan plan = SourcingUtils.findPlanBasedOnStrategies(
4        SourcingExecutionParameters.builder()
5            .context(context)
6            .sourcingContext(sourcingContext)
7            .profile(profile)
8            .positionStatuses(ImmutableList.of(Constants.Status.ACTIVE))
9            .build()
10    );
11}

Sourcing Profile Reference

The rule property referencing the sourcing profile should be named `sourcingProfileRef`.

`getUnfulfilledItems()`

Computes outstanding order items after accounting for allocated but non-rejected quantities.

1List<OrderItem> unfulfilledItems = SourcingUtils.getUnfulfilledItems(sourcingContext);

`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);

Overview

Key points

Context Management: Creates and manages Sourcing Context for the sourcing process.
Data Loading: Handles loading of order, item and required information.

Core Methods

`loadSourcingContext()`

Loads and creates a Sourcing Context with all necessary information such as order details, unfulfilled items, and supporting data required for sourcing decisions.

1SourcingContext sourcingContext = SourcingContextUtils.loadSourcingContext(
2    context, 
3    SourcingUtils::getUnfulfilledItems
4);

Overview

Key points

Order-Specific Operations: Handles order-related sourcing operations
Fulfillment Creation: Creates fulfillment records based on sourcing plans
Fulfillment Type Management: Sets fulfillment types based on business rules
Order Item Management: Manages order items and their allocation to fulfillments

Core Methods

`createFulfilments()`

Creates fulfillments from a `SourcingPlan`, allocating order items to locations and assigning fulfillment types.

Each `FulfilmentItem` includes an `availableQty` field that records the available quantity at the sourcing location at the time of plan generation
Fulfillment `refs` are assigned deterministically (`{orderId}-{fulfilmentChoiceId}-{index}`) - derived from the `SourcingContext` Id (e.g., order Id), fulfillment choice Id, and a consecutive index starting from the number of already existing fulfillments. This ensures that two sourcing processes running concurrently for the same fulfillments produce identical refs, preventing duplicate fulfillment creation

1// Create fulfillments from the sourcing plan
2List<Fulfilment> createdFulfilments = OrderUtils.createFulfilments(
3    context, 
4    sourcingContext, 
5    plan.getFulfilments()
6);

Configuration Tip

Duplicate fulfillment prevention during concurrent re-sourcing requires explicit configuration of `fc.api.fulfilment.uniqueness` = `REF_ONLY`. Without this setting, concurrent sourcing behavior is unchanged.

`fillFulfilmentType()`

Determines and assigns a fulfillment type for each fulfillment based on the Sourcing Context characteristics such as location type and delivery method.

1// Set fulfillment types based on business rules
2OrderUtils.fillFulfilmentType(sourcingContext, fulfilments);

`itemsMinusFulfilments()`

Subtracts the item quantities in a set of fulfillments from a list of order items. This can be used to determine the remaining order items after a set of proposed (but not yet created) fulfillments.

1// Get unfulfilled items
2List<OrderItem> unfulfilledItems = SourcingUtils.getUnfulfilledItems(context);
3
4// Find partial fulfillment
5Optional<Fulfilment> partialFulfilmentOpt = SourcingUtils.findHighestValuePartialFulfilment(
6    locationAndPositions,
7    unfulfilledItems,
8    Collections.emptySet() // No excluded locations
9);
10
11// Calculate remaining items after partial fulfillment
12if (partialFulfilmentOpt.isPresent()) {
13    Fulfilment partialFulfilment = partialFulfilmentOpt.get();
14    List<OrderItem> remainingItems = OrderUtils.itemsMinusFulfilments(
15        unfulfilledItems,
16        Arrays.asList(partialFulfilment)
17    );
18}

Overview

Key points

Location-Based Decisions: Handles location-specific sourcing logic.
Distance Calculations: Calculates distances between locations for proximity-based sourcing.
Location Availability: Checks if locations are active and available for sourcing.
Caching Optimization: Provides location-based caching optimization.

Core Methods

`getLocationByRef()`

Loads a single Location by provided reference, with caching for performance.

1Location location = LocationUtils.getLocationByRef(context, "store-123");

`getLocationsInNetwork()`

Load all the locations in a network with caching for performance.

1List<Location> networkLocations = LocationUtils.getLocationsInNetwork(
2    context, 
3    "network-001"
4);

`getLocationsInNetworks()`

Loads all locations that belong to the provided networks.

1List<String> networkRefs = Arrays.asList("network-001", "network-002", "network-003");
2List<Location> allLocations = LocationUtils.getLocationsInNetworks(context, networkRefs);

`distanceInMetres()`

Calculate distance between two points in latitude and longitude using the Haversine formula.

1Location storeLocation = LocationUtils.getLocationByRef(context, "store-123");
2Location customerLocation = LocationUtils.getLocationByRef(context, "customer-location");
3
4if (storeLocation != null && customerLocation != null && 
5    storeLocation.getPrimaryAddress() != null && customerLocation.getPrimaryAddress() != null) {
6    
7    double distance = LocationUtils.distanceInMetres(
8        storeLocation.getPrimaryAddress().getLatitude(),
9        storeLocation.getPrimaryAddress().getLongitude(),
10        customerLocation.getPrimaryAddress().getLatitude(),
11        customerLocation.getPrimaryAddress().getLongitude()
12    );
13    
14    // Check if within delivery radius (e.g., 50km)
15    if (distance <= 50000) {
16        context.action().log("Location is within delivery radius");
17    }
18}

Overview

Key points

Fulfillment Plan Creation: Persists a `SourcingPlan` as a `FulfilmentPlan` under the fulfillment option entity
ETA Calculation: Accepts an optional `EtaCalculator` to calculate and set ETA on the plan and on each individual fulfillment. When no `EtaCalculator` is provided, ETA fields are omitted
Available Quantity: Each `FulfilmentItem` in the plan records the available quantity at the sourcing location at the time of plan generation

Core Methods

`createFulfilmentPlan()`

Persists a `SourcingPlan` as a `FulfilmentPlan` under the fulfillment option entity.

Returns early without action if `context`, `plan`, or `sourcingContext` is `null`, or if the plan contains no fulfillments
Each item includes `productRef`, `requestedQuantity`, and `availableQuantity`
If an `EtaCalculator` is provided, ETA is calculated and set for the plan and for each fulfillment separately

1// With ETA calculation
2EtaCalculator etaCalculator = (sourcingPlan, fulfilment) -> {
3    // Calculate and return ETA for the given fulfilment
4    return ZonedDateTime.now().plusDays(3);
5};
6
7FulfilmentOptionsUtils.createFulfilmentPlan(context, sourcingPlan, sourcingContext, etaCalculator);
8
9// Without ETA calculation
10FulfilmentOptionsUtils.createFulfilmentPlan(context, sourcingPlan, sourcingContext, null);

How Sourcing Utilities work

Overview

Sourcing Utilities Overview

Overview

Key points

Value Proposition

Explanation through an Example

How Sourcing Utilities Help

What Happens Behind the Scenes

Related content

Sourcing Utilities

How Sourcing Utilities work

Sourcing Utils

Sourcing Context Utils

Order Utils

Location Utils

Fulfillment Options Utils

Sourcing Utils

Overview

Key points

Core Methods

`getPlanFinder()`

`findPlanBasedOnStrategies()`

`getBasedOnStrategiesPlanFinder()`

`findPlanBasedOnFallbackStrategies()`

`getBasedOnFallbackStrategiesPlanFinder()`

`buildRejectedFulfilment()`

Supporting Methods

`findPlanForAllItems()`

`findHighestValuePartialFulfilment()`

`findPartialFulfilmentPlan()`

`loadPositions()`

`loadSourcingProfile()`

`getUnfulfilledItems()`

`getNetworkRef()`

`getVirtualCatalogueRef()`

`getMaxSplit()`

Related content

How Sourcing Utilities work

Sourcing Utilities Overview

Sourcing Context Utils

Overview

Key points

Core Methods

`loadSourcingContext()`

Related content

How Sourcing Utilities work

Sourcing Utilities Overview

Order Utils

Overview

Key points

Core Methods

`createFulfilments()`

`fillFulfilmentType()`

`itemsMinusFulfilments()`

Related content

How Sourcing Utilities work

Sourcing Utilities Overview

Location Utils

Overview

Key points

Core Methods

`getLocationByRef()`

`getLocationsInNetwork()`

`getLocationsInNetworks()`

`distanceInMetres()`

Related content

How Sourcing Utilities work

Sourcing Utilities Overview

Fulfillment Options Utils

Overview

Key points

Core Methods

`createFulfilmentPlan()`

Related content

How Sourcing Utilities work

Sourcing Utilities Overview

Related content

Utility Bundles Overview

Getting Started with the Utility Bundles