Create Custom Sourcing Criterion

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

How-to Guide

Author:

Kirill Gaiduk

Changed on:

16 Apr 2026

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

Responsive Sourcing Framework Overview

Sourcing Utilities Overview

Sourcing Criteria Overview

Getting Started with Reference Sourcing Criteria

Steps

Preliminary Setup

Start with your own custom module setup.1. Create a custom module.

Reminder

Check the Module Recipe - Plugin Setup and Installation Guide for details.

2. Include Sourcing Utilities in your plugin dependencies.Your plugin must have access to its own copy of `util-sourcing` at runtime so it can initialize its own local sourcing registries.You can include it in your project by:

Adding it as a dependency in your `pom.xml`

1<dependency>
2    <groupId>com.fluentcommerce</groupId>
3    <artifactId>util-sourcing</artifactId>
4    <version>${util-sourcing.version}</version>
5</dependency>

Using a provided JAR, depending on your build setup

Reminder

Each plugin runs in an isolated classloader. Your custom Sourcing Conditions / Criteria will only be available if `util-sourcing` is included in the same plugin where your custom logic is implemented and executed
General Utility Bundles guidelines also apply to Sourcing Utilities

3. Optionally, download the Sourcing Utilities Java source package to review reference implementations.

Implement a Custom Sourcing Criterion Function

Create a class that enforces your ranking (exclusion) logic:

Implement `SourcingCriterion` (or extend `BaseSourcingCriterion`).
(When extending `BaseSourcingCriterion`) Put computation in `execute(CriterionContext ctx)`.
(If needed) Parse configuration in `parseParams(JsonNode params)`.
(Optional) Override `normalize(min, max, rating)` when your metric is “lower is better” (e.g., distance).

1@SourcingCriterionInfo(
2    name = "CustomSourcingCriterion",
3    type = "company.sourcing.criterion.custom",
4    tags = { "ATS-agnostic" } // or "ATS-dependent", "Exclusion"
5)
6public class CustomSourcingCriterion 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, and 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, higher score is better.
21        return 0.75f;
22    }
23
24    // Override normalize(...) only if the default doesn’t fit your scale.
25}

Tips

Return only a float (use `-1f` for location exclusion)
Validate required data from the context; handle nulls defensively
Mirror conventions from reference Criteria:
- naming
- logging
- units

Introduce Custom Sourcing Rules

Introduce custom versions of the Sourcing Rules that will execute your sourcing logic inside your plugin.

Note

Custom type registration and Rule execution must be initialized within the same plugin module.Creating custom Rules ensures that your Sourcing Condition or Criterion type is available during runtime evaluation.

1. Copy the reference Sourcing Rule implementation:

2. Rename the class3. Register your custom Sourcing Condition or Criterion inside the Rule class

1@RuleInfo(
2        name = "CustomCreateFulfilmentWithSourcingProfile",
3        description = "Applies Sourcing Profile {" + "profileRef" + "} to a sourcing request (Order, Fulfilment Option, etc.) and produces Fulfillment(s)",
4        accepts = {@EventInfo(entityType = "ORDER"),
5                @EventInfo(entityType = "FULFILMENT_CHOICE")}
6)
7@ParamString(name = "profileRef", description = "Profile reference to apply.")
8@Slf4j
9public class CustomCreateFulfilmentWithSourcingProfile implements Rule {
10
11    static {
12        // register custom sourcing criterion
13        SourcingCriteriaTypeRegistry.register("company.sourcing.criterion.custom", CustomSourcingCriterion.class);
14        // register custom sourcing condition
15        SourcingConditionTypeRegistry.register("company.sourcing.condition.custom", CustomSourcingCondition.class);
16    }
17
18    @Override
19    public void run(Context context) {
20        SourcingProfile sourcingProfile = loadSourcingProfile(context);
21        if (sourcingProfile.getSourcingStrategies() != null) {
22            SourcingContext sourcingContext = loadSourcingContext(context, SourcingUtils::getUnfulfilledItems);
23            SourcingUtils.SourcingPlan plan = findPlanBasedOnStrategies(context, sourcingContext, sourcingProfile,
24                    ImmutableList.of("ACTIVE", "AT_RISK"), null);
25            if (plan.getFulfilments() != null) {
26                fillFulfilmentType(sourcingContext, plan.getFulfilments());
27                createFulfilments(context, sourcingContext, plan.getFulfilments());
28            }
29        }
30    }
31}

4. Replace the reference Rule in your Workflow configuration with your custom Rule

Reminder

Each plugin initializes its own Sourcing registries.To ensure correct registration and runtime resolution of custom Sourcing Conditions or Criteria, your custom Rule must:

Include `util-sourcing` in the plugin’s `pom.xml`
Register custom types inside the same plugin where the Rule executes

Expose the Criterion Schema

Create (or update the existing) the Setting `fc.rubix.order.sourcing.criteria.custom` with your new Criterion schema.

1mutation createSetting ($input: CreateSettingInput) {
2    createSetting (input: $input) {
3        id
4        name
5        valueType
6        lobValue
7        value
8        context
9        contextId
10    }
11}

1{
2  "input": {
3    "name": "fc.rubix.order.sourcing.criteria.custom",
4    "valueType": "JSON",
5    "lobValue": [
6      {
7      "name": "CustomSourcingCriterion",
8      "type": "company.sourcing.criterion.custom",
9      "tags": [
10        "Lorem ipsum"
11      ],
12      "params": [
13        {
14        "name": "parameter1",
15        "value": "Lorem ipsum"
16        },
17        {
18        "name": "parameterN",
19        "value": "Lorem ipsum"
20        }
21      ]
22      }
23    ],
24    "value": "",
25    "context": "RETAILER",
26    "contextId": 1
27  }
28}

1{
2    "data": {
3        "createSetting": {
4            "id": "13142",
5            "name": "fc.rubix.order.sourcing.criteria.custom",
6            "valueType": "JSON",
7            "lobValue": [
8                {
9                    "name": "CustomSourcingCriterion",
10                    "type": "company.sourcing.criterion.custom",
11                    "tags": [
12                        "Lorem ipsum"
13                    ],
14                    "params": [
15                        {
16                            "name": "parameter1",
17                            "value": "Lorem ipsum"
18                        },
19                        {
20                            "name": "parameterN",
21                            "value": "Lorem ipsum"
22                        }
23                    ]
24                }
25            ],
26            "value": "",
27            "context": "RETAILER",
28            "contextId": 1
29        }
30    }
31}

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.

Related artifacts

fc.rubix.order.sourcing.criteria

Related content

Copyright © 2024-2026 Fluent Retail Pty Ltd (trading as Fluent Commerce). Unless otherwise expressly stated in a current written agreement with Fluent Commerce or any of its affiliates or on any single page of the docs.fluentcommerce.com site, use of the materials on this site is strictly limited to viewing by individuals over 18 years old for legitimate commercially appropriate reasons; and any downloading, copying or other actions or uses of any kind or by any means of the materials on this site, including by artificial intelligence tools, is strictly prohibited. All other rights reserved.

Implement a Custom Sourcing Criterion Function

Create a class that enforces your ranking (exclusion) logic:

Implement `SourcingCriterion` (or extend `BaseSourcingCriterion`).
(When extending `BaseSourcingCriterion`) Put computation in `execute(CriterionContext ctx)`.
(If needed) Parse configuration in `parseParams(JsonNode params)`.
(Optional) Override `normalize(min, max, rating)` when your metric is “lower is better” (e.g., distance).

1@SourcingCriterionInfo(
2    name = "CustomSourcingCriterion",
3    type = "company.sourcing.criterion.custom",
4    tags = { "ATS-agnostic" } // or "ATS-dependent", "Exclusion"
5)
6public class CustomSourcingCriterion 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, and 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, higher score is better.
21        return 0.75f;
22    }
23
24    // Override normalize(...) only if the default doesn’t fit your scale.
25}

Tips

Return only a float (use `-1f` for location exclusion)
Validate required data from the context; handle nulls defensively
Mirror conventions from reference Criteria:
- naming
- logging
- units

Introduce Custom Sourcing Rules

Introduce custom versions of the Sourcing Rules that will execute your sourcing logic inside your plugin.

Note

1. Copy the reference Sourcing Rule implementation:

2. Rename the class3. Register your custom Sourcing Condition or Criterion inside the Rule class

1@RuleInfo(
2        name = "CustomCreateFulfilmentWithSourcingProfile",
3        description = "Applies Sourcing Profile {" + "profileRef" + "} to a sourcing request (Order, Fulfilment Option, etc.) and produces Fulfillment(s)",
4        accepts = {@EventInfo(entityType = "ORDER"),
5                @EventInfo(entityType = "FULFILMENT_CHOICE")}
6)
7@ParamString(name = "profileRef", description = "Profile reference to apply.")
8@Slf4j
9public class CustomCreateFulfilmentWithSourcingProfile implements Rule {
10
11    static {
12        // register custom sourcing criterion
13        SourcingCriteriaTypeRegistry.register("company.sourcing.criterion.custom", CustomSourcingCriterion.class);
14        // register custom sourcing condition
15        SourcingConditionTypeRegistry.register("company.sourcing.condition.custom", CustomSourcingCondition.class);
16    }
17
18    @Override
19    public void run(Context context) {
20        SourcingProfile sourcingProfile = loadSourcingProfile(context);
21        if (sourcingProfile.getSourcingStrategies() != null) {
22            SourcingContext sourcingContext = loadSourcingContext(context, SourcingUtils::getUnfulfilledItems);
23            SourcingUtils.SourcingPlan plan = findPlanBasedOnStrategies(context, sourcingContext, sourcingProfile,
24                    ImmutableList.of("ACTIVE", "AT_RISK"), null);
25            if (plan.getFulfilments() != null) {
26                fillFulfilmentType(sourcingContext, plan.getFulfilments());
27                createFulfilments(context, sourcingContext, plan.getFulfilments());
28            }
29        }
30    }
31}

4. Replace the reference Rule in your Workflow configuration with your custom Rule

Reminder

Each plugin initializes its own Sourcing registries.To ensure correct registration and runtime resolution of custom Sourcing Conditions or Criteria, your custom Rule must:

Include `util-sourcing` in the plugin’s `pom.xml`
Register custom types inside the same plugin where the Rule executes

Expose the Criterion Schema

Create (or update the existing) the Setting `fc.rubix.order.sourcing.criteria.custom` with your new Criterion schema.

1mutation createSetting ($input: CreateSettingInput) {
2    createSetting (input: $input) {
3        id
4        name
5        valueType
6        lobValue
7        value
8        context
9        contextId
10    }
11}

1{
2  "input": {
3    "name": "fc.rubix.order.sourcing.criteria.custom",
4    "valueType": "JSON",
5    "lobValue": [
6      {
7      "name": "CustomSourcingCriterion",
8      "type": "company.sourcing.criterion.custom",
9      "tags": [
10        "Lorem ipsum"
11      ],
12      "params": [
13        {
14        "name": "parameter1",
15        "value": "Lorem ipsum"
16        },
17        {
18        "name": "parameterN",
19        "value": "Lorem ipsum"
20        }
21      ]
22      }
23    ],
24    "value": "",
25    "context": "RETAILER",
26    "contextId": 1
27  }
28}

1{
2    "data": {
3        "createSetting": {
4            "id": "13142",
5            "name": "fc.rubix.order.sourcing.criteria.custom",
6            "valueType": "JSON",
7            "lobValue": [
8                {
9                    "name": "CustomSourcingCriterion",
10                    "type": "company.sourcing.criterion.custom",
11                    "tags": [
12                        "Lorem ipsum"
13                    ],
14                    "params": [
15                        {
16                            "name": "parameter1",
17                            "value": "Lorem ipsum"
18                        },
19                        {
20                            "name": "parameterN",
21                            "value": "Lorem ipsum"
22                        }
23                    ]
24                }
25            ],
26            "value": "",
27            "context": "RETAILER",
28            "contextId": 1
29        }
30    }
31}

Create Custom Sourcing Criterion

Key Points

Prerequisites

Responsive Sourcing Framework Overview

Sourcing Utilities Overview

Sourcing Criteria Overview

Getting Started with Reference Sourcing Criteria

Steps

Preliminary Setup

Implement a Custom Sourcing Criterion Function

Introduce Custom Sourcing Rules

Expose the Criterion Schema

Verify the Criterion Behavior

Related artifacts

fc.rubix.order.sourcing.criteria

Related content

Responsive Sourcing Framework Overview

Getting Started with Reference Sourcing Criteria

Create Custom Sourcing Condition

Kirill Gaiduk

Building Blocks

By Type

Helpful Resources

Quick Links

Preliminary Setup

Implement a Custom Sourcing Criterion Function

Introduce Custom Sourcing Rules

Expose the Criterion Schema

Verify the Criterion Behavior