Sourcing Utilities Overview
Essential knowledge
Intended Audience:
Technical User
Author:
Holger Lierse
Changed on:
25 Sept 2025
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.
Prerequisites
These 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 - Sourcing Conditions and Criteria Management: Provides functions, registration, and execution logic for tailoring Sourcing Strategies to the specific needs of customers
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);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.
