How Sourcing Criteria work
Author:
Kirill Gaiduk
Changed on:
25 Sept 2025
Overview
This article introduces Sourcing Criteria as the ranking (and exclusion) functions that score candidate Locations during Strategy evaluation. You’ll learn how Criteria order affects final rankings, which reference Criteria are available, and how to extend the library with custom implementations.
Sourcing Criteria Overview
Author:
Kirill Gaiduk
Changed on:
2 Oct 2025
Overview
Sourcing Criteria determine which eligible Locations are best once a Strategy applies. You’ll learn how to configure, sequence, and extend Criteria so your prioritization is predictable and explainable across business scenarios.
Key points
- Define prioritization with configurable Sourcing Criteria that score and order candidate Locations
- Reference Sourcing Criteria schema is global and can be extended or overridden with customer-specific definitions for tailored Strategies
- Criterion Utilities provide reference functions, normalization, and a registry/annotations model for custom extensions
- Configure all Criteria with clear names, parameters, and evaluation order to ensure accurate and predictable ranking
What is a Sourcing Criterion?
A Sourcing Criterion is a function that returns a numeric rating for a Location (or excludes it by returning -1). Criteria are evaluated only after a Strategy passes its Conditions. Typical examples:
- Proximity:
`locationDistance`,`locationDistanceBanded`,`locationDistanceExclusion` - Availability-driven:
`inventoryAvailability`,`inventoryAvailabilityBanded`,`inventoryAvailabilityExclusion` - Business preference:
`networkPriority`,`locationTypeExclusion`,`locationNetworkExclusion` - Operational:
`locationDailyCapacity`
Architectural Context
Sourcing Criteria are part of the Responsive Sourcing Framework within the Fluent platform. They sit in several places within the platform, each serving a distinct role:
1. Sourcing Criterion Entity
Sourcing Criterion Entity is represented by the `SourcingCriterion` GraphQL type.
It refers to an individual, concrete instance of a Sourcing Criterion that is configured as part of a Sourcing Strategy.
Structure
Field | Type | Description | Notes |
|
| Name of the Sourcing Criterion | The Reference Sourcing Criteria schema (specified in the |
|
| Type of the Sourcing Criterion | The |
|
| Parameters of the Sourcing Criterion | The Parameters configure Sourcing Criteria to support specific customer sourcing logic Available configuration options are defined with the |
2. Sourcing Criteria Schema
The Sourcing Criteria schema is located in the dedicated Setting(s):
`fc.rubix.order.sourcing.criteria`stores reference (`GLOBAL`) Sourcing Criteria schema`fc.rubix.order.sourcing.criteria.custom`can be created for customer-specific (`ACCOUNT`/`RETAILER`) Sourcing Criteria schema
It defines the structure of a Criterion and specifies which parameters it can include. In practice, it acts as the template for a Sourcing Criterion that is added to the Criteria library, making it available for configuration and use by end users.
3. Criterion Utilities
Criterion Utilities are an integral part of the Sourcing Utilities bundle.
They include:
- Reference Criterion Functions
- Implemented as classes extending
`BaseSourcingCriterion` - Each class encapsulates the logic for scoring (or excluding) Locations, for example:
`LocationDistanceCriterion`– calculates distance between destination and Location`InventoryAvailabilityCriterion`– evaluates available stock coverage`NetworkPriorityCriterion`– prioritizes Locations based on Network membership
- Criterion classes can override
`normalize()`to adjust rating scales (e.g., smaller distance = higher score)
- Implemented as classes extending
- Annotations and Auto-Generation
`@SourcingCriterionInfo`- defines metadata such as`name`,`type`,`tags`, and`label``@SourcingCriterionParam`- specifies configurable parameters, UI component type, and options- These annotations are processed to automatically generate the Sourcing Criteria Schema JSON, which feeds the configuration UI
- Helper Methods (
`SourcingCriteriaUtils`)`CriteriaArray`- stacks multiple Criteria for sequential evaluation and tie-breaking`normalize()`- scales ratings across all candidate Locations into a [0..1] range- Utility methods (
`getFloats`,`getStrings`,`getDistanceUnits`) - parse parameter values from JSON configs `getCriteria(...)`- merges default and Strategy-specific Criteria into a single evaluation stack
- Criterion Registry (
`SourcingCriteriaTypeRegistry`)- Registers and retrieves Criterion classes by their type identifier
- Dynamically instantiates Criterion implementations during Strategy evaluation
- Supports extension with custom Criterion classes through explicit registration
Features
Within the Responsive Sourcing Framework, Sourcing Criteria provide the ability to:
- Prioritize fulfillment Locations by configuring Criteria that score, rank, or exclude candidates
- Leverage the reference library of predefined Sourcing Criteria, with flexible parameters and configuration options
- Develop new Sourcing Criteria using recommended patterns and best practices to extend ranking logic as needed
Related content
Getting Started with Reference Sourcing Criteria
Author:
Kirill Gaiduk
Changed on:
26 Sept 2025
Key Points
- Understand the Ranking Mechanism: Sourcing Criteria score (or exclude) candidate Locations to drive ranking and tie-breaking
- Sequence Matters: Criteria are evaluated top-to-bottom; the first Criterion decides the primary order, the next acts as a tie-breaker
- Normalize Ratings: Most Criteria return raw numeric ratings that the framework normalizes across Locations to ensure consistent comparisons
- Use Exclusion Carefully: Some Criteria return a negative score (-1) to exclude Locations; apply these early in the stack for predictable outcomes
- Know When to Extend: The reference library covers common distance, inventory availability, and priority logic; develop a custom Criterion for domain-specific logic
Prerequisites
Steps
Core Concept
A Sourcing Criterion is a configurable function that evaluates a candidate Location in context of the Sourcing Request and returns a rating:
- A positive float (0…1) ranks how suitable a Location is
- -1 filters a Location out of consideration
- Criteria are applied in sequence to produce a final ranked list of eligible Locations
During Strategy evaluation, the framework instantiates the Criterion class defined by `type` (for example, `fc.sourcing.criterion.locationDistance`) and applies its `apply()` method to every candidate Location.
Internal Mechanics
Reference Criteria share common behavior through `BaseSourcingCriterion` and Criterion Utilities:
- Apply → Execute → Normalize:
`apply()`calls pre-logic, executes business rules, and post-logic`normalize()`adjusts raw scores to a [0–1] range where applicable
- Sequential Stack:
- Criteria are applied in order of appearance
- The first Criterion usually defines the main ranking dimension (e.g., distance or inventory availability)
- Later Criteria resolve ties
- Parameter Parsing:
`parseParams()`reads JSON params defined in the`fc.rubix.order.sourcing.criteria`Setting- Helper Utilities (
`getFloats`,`getStrings`,`getDistanceUnits`) ensure correct types and default handling
Reference Sourcing Criterion Functions
Class (Criterion Utilities) | Type (Sourcing Criteria Schema) | Description (UI) | Notes |
|
| Prioritises locations that are geographically closer to the delivery address |
|
|
| Ranks locations by distance bands {{value}}, prioritising bands that are closer |
|
|
| Excludes locations that are farther than {{value}}{{value}} | Excludes (-1) Locations beyond a specified maximum distance threshold (in km or miles) |
|
| Prioritises locations with the highest available daily fulfillment capacity | Rates Locations based on their |
|
| Prioritises locations by the specified network ranking {{value}} |
Example:
|
|
| Prioritises locations based on total units of inventory requested in the order that can be fulfilled |
Example:
Note: A Location with surplus Inventory that does not fulfill the entire Sourcing Request may still receive a higher score than a Location that fully satisfies the Request. However, the framework prioritizes the Fulfillment Plan with the fewest Fulfillments overall |
|
| Ranks locations by fulfillment percentage bands {{value}}, prioritising bands with higher availability |
|
|
| Excludes locations where inventory availability for a given order, is less than {{value}}% | Excludes (-1) Locations that do not meet the configured minimum fulfillment threshold (in %) |
|
| Excludes locations of type {{value}} | Excludes (-1) Locations whose type matches a configured value(s) (e.g., store vs. warehouse) |
|
| Excludes locations that are members of one of the following networks {{value}} |
|
|
| Prioritises locations that fulfill a higher monetary portion of the order |
Example:
Note: Unlike |
Default Sourcing Criteria
Class | Type | Notes |
|
| Automatically excludes Locations that previously rejected Items in the same Sourcing Request (applied by default, not shown in UI) |
Parameter Definitions
Sourcing Criteria rely on parameters defined in the `fc.rubix.order.sourcing.criteria` Setting to ensure valid configuration:
`value`: Numeric thresholds or band breakpoints. An input like [10, 25, 50] defines 4 bands:- (–∞ … 10]
- (10 … 25]
- (25 … 50]
- (50 … +∞)
`valueUnit`: Selects unit of measure where applicable (kilometres, miles)`component`: UI input type such as`fc.field.multistring`,`integer`, or`select``mandatory`/`exactSearch`: Validation flags controlling whether the field must be provided and if exact match applies
Correct parameter definition guarantees consistent evaluation in both UI and runtime.
Configuration in the UI
The reference schema in `fc.rubix.order.sourcing.criteria` Setting defines templates for all reference Sourcing Criteria. Each template specifies the required UI components and their validation rules to ensure that Criteria parameters are entered consistently and correctly.
For account/retailer-specific adjustments, override Criteria in `fc.rubix.order.sourcing.criteria.custom`. When a Criterion with the same `name` exists in both schemas, the custom schema takes precedence, allowing organizations to tailor global definitions to their own business needs without breaking the baseline.
Attaching Criteria to Strategies
Sourcing Criteria are added to Primary or Fallback Sourcing Strategies via the Sourcing Profile GraphQL API, similar to Conditions.
Best Practices
- Order Criteria deliberately: put Exclusion Criteria first, then your primary ranking Criterion, then tie-breakers
- Provide exact values and enforce strict types via schema-driven components (e.g., units in select, numeric bands)
- Test boundary and edge cases thoroughly
- Apply overrides in
`fc.rubix.order.sourcing.criteria.custom`when tailoring Criteria for specific Accounts / Retailers
Related artifacts
Related content
Create Custom Sourcing Criterion
Author:
Kirill Gaiduk
Changed on:
26 Sept 2025
Key Points
- Outcome: You’ll extend the Responsive Sourcing Framework with a Custom Criterion and apply it in real Strategies
- Minimal essentials: Implement the Criterion → register it → expose it in the Setting (auto-generate or manual) → verify behavior
- Application: Influence Location ranking (exclusion) with domain-specific scoring that fits your business
Prerequisites
Steps
Preliminary Setup
Custom Sourcing Criterion creation requires modifying the Sourcing Utilities bundle:
1. Prepare your module that contains Order Reference Module assets.
2. Download the Sourcing Utilities Package (Java source code).
3. Add Sourcing Utilities as a dependency in your project's ``pom.xml`` file.
Implement a Custom Sourcing Criterion Function
Create a class that enforces your ranking (exclusion) logic:
- Implement
`SourcingCriterion`(or extend`BaseSourcingCriterion`) - Put computation in
`execute(CriterionContext ctx)`(when extending`BaseSourcingCriterion`) - Parse configuration in
`parseParams(JsonNode params)`if needed - (Optional) Override
`normalize(min, max, rating)`when your metric’s “lower is better” (e.g., distance)
1@SourcingCriterionInfo(
2 name = "mySourcingCriterion",
3 type = "company.sourcing.criterion.my",
4 tags = { "ATS-agnostic" } // or "ATS-dependent", "Exclusion"
5)
6public class MySourcingCriterion extends BaseSourcingCriterion {
7
8 @SourcingCriterionParam(name = "value", component = "integer")
9 private Integer threshold;
10
11 @Override
12 public void parseParams(final JsonNode params) {
13 // parse threshold, lists, units, etc.
14 }
15
16 @Override
17 protected float execute(final SourcingCriteriaUtils.CriterionContext ctx) {
18 // Return:
19 // -1f to exclude a location,
20 // 0..1f (or any float) to score/rank a location.
21 return 0.75f;
22 }
23
24 // Override normalize(...) only if the default doesn’t fit your scale
25}Register the Criterion in the Type Registry
Register a unique `type` with `SourcingCriteriaTypeRegistry`.
1static { SourcingCriteriaTypeRegistry.register("company.sourcing.criterion.my", new MySourcingCriterion());}Expose the Criterion Schema
Create (or update the existing) the Setting `fc.rubix.order.sourcing.criteria.custom` with your new Criterion schema, similar to Conditions.
Schema Autogeneration
Sourcing Criteria support annotation-driven generation of the Setting JSON.
How it works
- The generator scans all classes registered in
`SourcingCriteriaTypeRegistry`. - Reads
`@SourcingCriterionInfo`+`@SourcingCriterionParam`annotations - Produces a complete JSON (name, type, tags, params, including select options)
Run it
- Command:
`java -jar <path>util-sourcing-<version>-sources.jar` - Output: SourcingCriteriaSetting.json in the same folder as the JAR/classes
- Use this JSON to populate
`fc.rubix.order.sourcing.criteria.custom`Setting
When to use
- Any time you add/update Sourcing Criteria or their
`params`- regenerate to keep UI configs in sync
Verify the Criterion Behavior
- Use the Sourcing Profile GraphQL API to add the new Criterion to a Sourcing Strategy.
- Test against different Sourcing Requests and confirm the expected outcomes.
