Fluent Commerce Logo
Docs
Help & Feedback

Basic Knowledge

Essential knowledge articles on Rules SDK

Dynamic Mutations

Essential knowledge`DynamicUpdateMutation` automatically derives the correct update Mutation for the primary Entity based on the `RulesetContext` and then performs the update on one or more fields.
  • Automatic Mutation Selection: GraphQL mutations are automatically selected from the `RulesetContext` based on entity type.
  • Flexible Field Updates: Update single fields or multiple fields in bulk using simple key-value pairs.
  • Type-Based Safety: Use POJO classes for strongly-typed updates with automatic field derivation.
  • Runtime Validation: Built-in validation ensures only valid fields are included in mutations.
  • Universal Application: Works across different entity types without requiring entity-specific mutation code.

Dynamic Queries and Utils

Essential knowledge`DynamicEntityQuery`, with the help of the `DynamicUtils` class, automatically derives the correct GraphQL query operation for the primary Entity from the `RulesetContext`. It dynamically retrieves fields related to that Entity, removing the need for pre-compiled queries while preserving type safety and performance.
  • Runtime Query Generation: Automatically builds GraphQL queries at runtime based on entity context, eliminating pre-compiled queries.
  • Dual Usage Patterns: Type-based mapping with POJO classes for strong typing, or path-based queries for maximum flexibility.
  • Universal & Validated: Works across different entity types with automatic schema validation and connection pattern handling.
  • Flexible Access: Results accessible as typed objects, JsonNode, or flattened maps with Lombok integration.
  • Connection Handling: Built-in support for paginated connections with automatic pagination handling via `queryList()` methods.
  • Dynamic Mutations: Update entity properties dynamically using key-value pairs without pre-compiled mutation queries.
  • Unified Data Access: `getJsonPath()` method provides unified access to both event and entity data using consistent path syntax.

What if I need to modify a Rule from a Module?

Essential knowledgeThis resource page offers detailed instructions on how to find assistance when looking to alter the Rules that are part of a Module.
  • Partner Support on modifying a Rule from a Module

Dynamic Utilities Overview

Essential knowledgeThe `util-dynamic` library is a collection of utility functions that allow you to generate GraphQL queries and mutations at runtime. This enables the creation of highly configurable and reusable rules that can adapt to different needs without requiring code changes.PrerequisitesThese articles assumes you're familiar with:
  • Java
  • Maven
  • JUnit
  • Dynamic Queries: Fetch any field from an entity at runtime by providing a POJO class that defines the desired data structure, eliminating the need for pre-compiled queries.
  • Dynamic Mutations: Update any field on an entity by passing a simple `Map` of key-value pairs, allowing for the creation of generic "field setter" rules.
  • Dynamic Connections: Easily query and iterate over paginated one-to-many relationships (like `order.items`), as the utility handles all the pagination logic for you.
  • Advanced JSON Path: A powerful `getJsonPath` method that can retrieve data from either the event or the entity itself, automatically determining the correct source.
  • Enhanced JSON Utilities: This bundle includes a more advanced `JsonUtils` with powerful methods for navigating and transforming complex JSON structures.

Sourcing Utilities Overview

Essential knowledgeThe `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
  • 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

Sourcing Utils

Essential knowledgeThe `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.
  • 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

Order Utils

Essential knowledgeThe `OrderUtils` class in the `util-sourcing` is a utility class that provides order-specific utilities for sourcing operations. It handles order-related sourcing operations including fulfillment creation, fulfillment type determination, and order item management.
  • 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.

Sourcing Context Utils

Essential knowledge`SourcingContextUtils` in the `util-sourcing` is a utility class for managing sourcing context and data loading operations. It provides methods to create and populate sourcing contexts with order details, unfulfilled items, and supporting data required for sourcing decisions.
  • Context Management: Creates and manages Sourcing Context for the sourcing process.
  • Data Loading: Handles loading of order, item and required information.

Location Utils

Essential knowledgeThe `LocationUtils` class in the `util-sourcing` is a utility class that provides utilities for location-based sourcing decisions. It handles location-specific sourcing logic including distance calculations, location availability checks, and provide location-based caching optimization.
  • 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.

Install & Run Rules SDK Prerequisites

Essential knowledgeThe software required to install and run Rules SDK, also known as the Fluent SDK.
  • JDK8.
  • Maven 3.6.
  • IntelliJ IDE
  • GraphQL Plugin
  • Postman

Rule Context Generator

Essential knowledgeThe `RuleContextGenerator` is the underlying class that the `RuleExecutor` and `WorkflowExecutor` use to construct a mock `Context` for your tests. While you will most often interact with it through the executors, you can also use it directly to manually create a `Context` object.This is particularly useful when you are unit testing a helper or utility class that requires a `Context` object as a parameter, but you don't need to execute a full rule.
  • Core Context Builder: `RuleContextGenerator` is the fundamental builder class that the `RuleExecutor` and `WorkflowExecutor` use to create the mock `Context` for your tests.
  • Direct Instantiation: You can use it directly (`RuleContextGenerator.of(...)`) when you need a `Context` object for testing a helper class or utility method, but don't need to execute a full rule.
  • Action Tracking: It automatically captures and tracks all actions (events, mutations, logs) performed during execution, providing methods like `getActionsOfType()` and `getLastActionOfType()` for verification.
  • Foundation of Testing: It is the foundational component of the test utilities, providing the mock environment that makes isolated unit and integration testing possible.

Rule Executor

Essential knowledgeThe `RuleExecutor` is the primary tool in the `util-test` library for unit testing a single rule in isolation. It provides a builder-style interface for setting up a mock `Context`, executing your rule's `run` method, and asserting the results.
  • Unit Testing Focus: `RuleExecutor` is the main tool for testing a single rule in isolation.
  • Arrange-Act-Assert: It's designed to follow the clean Arrange-Act-Assert pattern. You use the constructor to arrange the context, call `execute()` to act, and use `getActions()` to assert the outcome.
  • Rule Properties Configuration: Rule properties are passed as a `Map` in the `RuleExecutor.of(Class, Map)` constructor.
  • Event Configuration: Custom events can be passed to the `execute(Event)` method.
  • GraphQL Mocking: The `.mockNamedQuery()` method is a critical feature that allows you to provide predefined JSON responses for any GraphQL query your rule executes, enabling you to test different data scenarios without making live API calls.

Workflow Executor

Essential knowledgeWhile the `RuleExecutor` is perfect for unit testing a single Rule, the `WorkflowExecutor` is the tool of choice for integration testing an entire Workflow or parts of it. It reads a Workflow definition from a JSON file and simulates the Fluent Orchestration Engine by executing the sequence of Rules and Rulesets.
  • Integration Testing Focus: `WorkflowExecutor` is the primary tool for integration testing an entire or parts of a Workflow.
  • Workflow Simulation: It mimics the Fluent Commerce Orchestration Engine by processing an initial Event and then passing the resulting Event to the next Ruleset in the chain.
  • Rule Mocking: The `.mockRule()` method is a powerful feature that allows you to replace a real Rule in the Workflow with a mock implementation. This is crucial for isolating the part of the Workflow you want to test.
  • Targeted API Mocking: The `.mockNamedQuery()` method lets you mock a GraphQL query only when it is called by a specific Rule, giving you fine-grained control over test data for different stages of the Workflow.
  • Consolidated Assertions: The `execute` method returns a single Context containing a consolidated list of all Actions from all Rules, allowing you to assert the final state.

Deploy your Rule

Essential knowledgeIn this lesson, you will learn how to deploy and run a custom rule.
  •  Access to Fluent Training account is required

Utility Bundles Overview

Essential knowledgeThe Fluent Commerce Utility Bundles are a set of libraries designed to accelerate Rule development, reduce boilerplate code, and improve the overall quality and maintainability of implementations. They are the cornerstone of writing maintainable, reusable, and easily upgradeable Rules for the Fluent Commerce platform.
  • Prerequisites: You should have knowledge of the Rules SDK, including Designing Rules, Rule Structure, Writing Rules, Rule Development Guidelines, General Principles, and Rules SDK - Getting Started.
  • Focus on Business Logic: The libraries handle common, repetitive tasks (like data fetching and JSON conversion), allowing developers to concentrate on writing the business logic that delivers value.
  • Three Specialized Bundles: The utilities are organized into three modules: `util-core` for essential daily tasks, `util-dynamic` for building runtime queries, and `util-test` for simplifying testing.
  • Easy Upgrades: Receive bug fixes and new features from Fluent Commerce by updating the dependency version in your `pom.xml`, ensuring your implementation stays current.
  • Built for Extensibility: The utilities are designed to be flexible, allowing you to inject your custom logic into standard processes.

Test Utilities Overview

Essential knowledgeThe `util-test` library is a comprehensive collection of utility functions, mock objects, and executors designed to minimize the overhead and complexity of testing your Fluent Commerce rules.PrerequisitesThese articles assumes you're familiar with:
  • Java
  • Maven
  • JUnit
  • `RuleExecutor`: The primary tool for unit testing a single rule in isolation.
  • `WorkflowExecutor`: An advanced executor for integration testing an entire workflow from a JSON definition.
  • `RuleContextGenerator`: The underlying builder for creating the mock `Context`, allowing you to define the event, entity, properties, and mock API responses for your test.
  • `MockApiClient`: A critical component for providing predefined GraphQL responses, enabling you to test how your rule handles different API outcomes without making live calls.
  • `TestActions`: A helper object that captures all actions your rule performs and provides fluent assertions (e.g., `sendEvent().assertCount(1)`) to easily verify the results.

JSON Utilities

Essential knowledgeThe `JsonUtils` class in the `util-core` bundle provides a foundational set of helper methods for working with JSON data. Built on top of the Jackson library, these utilities simplify the conversion of raw JSON into usable Plain Old Java Objects (POJOs) and vice-versa.JSON is a common data format found in event attributes, entity attributes, and setting values, and these utilities are essential for effective rule development.
  • Universal Conversion (`anyToPojo`):This method can convert almost any Java object (especially `Map`s from event attributes) into a strongly-typed POJO, making the code safer and easier to read.
  • POJO to Map (`pojoToMap`): The reverse of `anyToPojo`. This is essential for when it is necessary to need to add a complex object as an attribute to a new event.
  • String to POJO (`stringToPojo`): Directly converts a raw JSON string into a typed POJO, which is useful when dealing with data from external systems or settings.
  • Built on Jackson: The utilities are built on the Jackson library.

Log Utilities

Essential knowledgeThe `LogUtils` class in the `util-core` bundle provides structured logging helpers that remove boilerplate code when using logging actions within your rules. These utilities make it easy to record key actions, errors, and checkpoints to the event log for debugging and auditing purposes.
  • Standardized Logging: The utilities provide a standard, structured format for log messages, making the event log easier to read and search.
  • Automatic Titling: The log entry's title is automatically generated from the rule's class name, ensuring consistency and saving you from writing boilerplate code.
  • Simple Checkpoints: `logOnce` is an easy way to record a specific outcome or checkpoint in your rule's execution with a formatted message.
  • Collections: `logAttributeCollection` is a convenient helper for logging a list of attributes.

Setting Utilities

Essential knowledgeThe `SettingUtils` class in the `util-core` bundle provides a robust set of tools for retrieving configuration settings from the Fluent Commerce API. A key feature of this utility is that it automatically respects the platform's setting hierarchy, ensuring that the most specific setting value is always returned.
  • Automatic Hierarchy: `SettingUtils` automatically respects the Fluent Commerce setting hierarchy (Location > Retailer > Account > Global), so you always get the most specific value without any extra work.
  • Type-Safe Conversion: The `.as(MyClass.class)` method allows you to convert a setting's value to any type—from simple primitives (`String`, `Integer`) to complex POJOs—in a single, null-safe operation.
  • Efficient Bulk Fetching: You can retrieve multiple settings (`getSettings`) or a group of settings by a common prefix (`getSettingsByNamespace`) in a single API call, which is more performant than fetching them one by one.

Query Utilities

Essential knowledgeThe `QueryUtils` class in the `util-core` bundle offers a set of functions to simplify GraphQL queries from within your Rules. These helpers make it easier to work with query results and handle common data structures like paginated connections.
  • Type-Safe Queries: The `query` method is a wrapper that eliminates the need to manually cast GraphQL responses to the correct type, making your code cleaner and safer.
  • Simplified Connections: `connectionToList` is a powerful helper that converts a standard GraphQL "connection" (with its `edges` and `nodes`) into a simple `List` of objects, removing a significant amount of boilerplate code.
  • Inline Transformation: `connectionToList` can also accept a function, allowing you to transform the list of GraphQL nodes into a list of your own domain objects (POJOs) in a single operation.

Rule Utilities

Essential knowledgeThe `RuleUtils` class in the `util-core` bundle provides helper methods to streamline the process of retrieving and validating Rule properties. Using these utilities helps ensure that your Rules are configured correctly and reduces the risk of runtime errors caused by missing or invalid parameters.
  • Flexible List Properties: `rulePropAsList` reliably parses a rule property into a `List`, whether it's configured as a comma-separated string or a JSON array. This is ideal for properties that require multiple values.
  • Configuration Validation: `validateRulePropsIsNotEmpty` provides a simple, one-line way to ensure that all required properties have been provided to a rule, preventing runtime errors.
  • Fail-Fast Errors: When validation fails, the utility throws a `PropertyNotFoundException` with a clear error message. This stops the rule from executing with an invalid configuration and makes debugging easier.

Event Utilities

Essential knowledgeThe `EventUtils` class in the `util-core` bundle provides a set of essential helper methods to simplify event creation, modification, and forwarding. Using these utilities helps to eliminate boilerplate code and prevent common errors, such as forgetting to copy event attributes or improperly handling event schedules.
  • Safe Event Handling: The utilities eliminate common errors by automatically handling attribute copying and schedule management when cloning or forwarding events.
  • Immutability: `Event` objects are immutable. `EventUtils` methods always return a new event instance when a modification is made.
  • Simplified Forwarding: Provides simple, one-line methods for common forwarding patterns, like cloning and sending an event immediately (`forwardInboundEventWithNewName`) or adding attributes (`forwardInlineEventWithAttributes`).
  • Type-Safe Attribute Access: Use `getEventAttributeAs` to retrieve and convert an event attribute to a specific type (including complex POJOs) in a single, null-safe operation.

Core Utilities Overview

Essential knowledgeThe Core Utility (`util-core`) is a standard library of utility functions designed to simplify and accelerate Rule development on the Fluent Commerce platform. It provides a foundational set of helper classes that address common development challenges - such as safely handling event attributes, retrieving and converting settings, logging consistently, and minimizing boilerplate code when forwarding events or querying data.PrerequisitesThese articles assumes you're familiar with:
  • Java
  • Maven
  • JUnit
  • Event Management (`EventUtils`): Simplifies creating and forwarding events, ensuring attributes are copied correctly.
  • Rule Properties (`RuleUtils`): Streamlines retrieving and validating rule properties to avoid configuration errors.
  • Query Simplification (`QueryUtils`): Eases the execution of GraphQL queries, especially for paginated data.
  • Settings Management (`SettingUtils`) : Simplifies retrieving settings and automatically converts them from JSON to POJOs.
  • Logging (`LogUtils`): Provides structured logging for easier debugging and auditing.
  • JSON Handling (`JsonUtils`): Offers helpers for JSON serialization, deserialization, and comparison.
  • Date Formatting (`GqlDateUtils`): A simple utility for handling GraphQL-compatible dates.

GraphQL Date Utilities

Essential knowledgeThe `GqlDateUtils` class in the `util-core` bundle provides a simple and effective set of functions for handling the specific date format required by the Fluent Commerce GraphQL API. The platform uses the ISO 8601 format (`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`), and this utility ensures you can easily parse and format dates to be compatible.
  • GraphQL Compatibility: This utility ensures that dates are always in the precise ISO 8601 string format required by the Fluent Commerce GraphQL API (`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`).
  • Parsing (`parseGqlDate`): Safely parses a string from an event or external system into a standard Java `Date` object, preventing common parsing errors.
  • Formatting (`toGqlDate`): Converts a Java `Date` object into the specific string format required when passing dates as variables in GraphQL queries or mutations.
  • Centralized Logic: Centralizes date handling to avoid bugs and ensure consistency across your entire implementation.

MockApiClient

Essential knowledgeThe `MockApiClient` is a critical component of the `util-test` library. It provides a mock implementation of the `ApiClient`, which is the interface Rules use to communicate with the Fluent Commerce GraphQL API.By using the `MockApiClient`, you can test how your Rule behaves with different API responses without making any actual network calls. This isolates your tests, makes them faster, and allows you to simulate any scenario, including errors or empty data results.
  • Test API Interactions: The `MockApiClient` allows you to test how your rule responds to different API outcomes (e.g., success, failure, empty data) without making live network calls.
  • Isolate and Speed Up Tests: By mocking the API, your tests run faster and are isolated from network or environment issues.
  • Executor Integration: You typically don't use `MockApiClient` directly. You use the helper methods on `RuleExecutor` and `WorkflowExecutor` (like `.mockQuery()` and `.mockSetting()`) to configure it.
  • Full Coverage: It supports mocking pre-compiled queries/mutations, dynamic queries/mutations, and settings, giving you complete control over your test environment.

Dynamic Pagination

Essential knowledge`DynamicConnectionQuery` automatically derives the Connection fields (arrays) for the primary Entity based on the `RulesetContext` and can dynamically load all connection items, with pagination handled internally.
  • Automatic Pagination: `DynamicUtils.queryList` completely automates fetching paginated data from a GraphQL connection. You get a simple `Iterable`, and the library handles fetching subsequent pages in the background as you iterate.
  • Lazy Loading: The utility is highly efficient because it uses a "lazy loading" approach. It only fetches the next page of data when you have iterated through the current one.
  • POJO-Driven: You define the data you need by creating a simple POJO class. The utility dynamically builds the GraphQL query to fetch only the fields defined in your POJO.
  • Server-Side Filtering: You can pass a `Map` of parameters to `queryList` to filter the connection on the server. This is much more efficient than fetching all the data and filtering it in your rule.

Test your Rule

Essential knowledgeIn this module, you will learn about Unit Testing and creating a Mocked Unit test for a custom Rule.  You will also learn how to perform testing on the TestExecutor and finally deploy your plugin into your sandbox environment
  • Unit Testing
  • PowerMock
  • TestExecutor
  • Testing on Sandbox

Exception Management, Debugging and Logging Events

Essential knowledgeThis section covers the Exception handling, Debugging and Logging in a Custom Rule
  • Custom Rule should be ready along with the Unit Test Cases
  • Effect of Exceptions on Event processing
  • IDE Debugging
  • Log Action

Case Scenario - Implement Fraud Check

Essential knowledgeIn this scenario we will implement a Fraud Check step in the Order Workflow
  • Prerequisites setup
  • Basics of Rule writing

Introduction to Fluent Rules

Essential knowledgeWorkflow Framework Rules are written using Java and contain a specific structure and metadata for describing and validating the Rule. In this lesson, you will learn how to write Rules by adding customised business logic. 
  • OMX Workflow -  Understand the Workflow Engine (previously 'Rubix Orchestration Engine'), Workflow Design Patterns, Workflow Builder
  • Workflow Framework - Understand the Workflow Framework, Events, and Triggers.

Plugin Structure & JS GraphQL

Essential knowledgeIn this module, you will learn about a Plugin Project structure and JS GraphQL within the Plugin Project.  You will also learn how to modify and run a JS GraphQL query.
  • Installed SDK
  • GQL Basics

Rules SDK Setup & Plugin Creation

Essential knowledgeIn this lesson, you will learn about Rules SDK, the Software Development Kit for Fluent Order Management, and the key features of the SDK.
  • Prerequisites software installation

Overview of Workflow Framework

Essential knowledgeYou'll acquire new knowledge of the Workflow Framework, its fundamental concepts and terminologies, and also learn about best practice workflow design concepts.  After covering the theory, you will get ‘hands-on’ by completing a Lab where you'll have a go at composing business logic (code free) via the Workflow Builder.
  • The Workflow Framework is a component of the Order Management Experience (OMX) platform and drives the business logic orchestration aspects of the Fluent Order Management.
  • The Workflow Framework enables flexible workflow customization via low-code configuration, high-performance and scalable processing, and seamless UI user action integration.
  • The Workflow Framework comprises the Workflow Engine, Workflow Builder, Rule Library, and Rules SDK.

Fluent Commerce Fundamentals

Essential knowledgeThis is a guidepost for Developers highlighting important guides and articles to speed up Fluent Commerce's learning process. 
  • Workflows that consist of states, rulesets, triggers, user actions, and Modules, used for distributing workflows and it's artifacts, are a key part of the Fluent Commerce platform.
  • Settings are used to adjust Workflow execution

Rules SDK Testing Rules

Essential knowledgeThis page describes the best practice testing approaches for rules and plugins.
  • As per standard industry practices, rules should be tested as part of the development cycle, on the developer's local machine.
  • Testing on Sandbox after local testing has been completed.

Workflow Framework and the Rules SDK

Essential knowledgeThis section covers the fundamentals of the Workflow Engine, provides an overview of the architecture, identifies key concepts, and prepares clients to build and use their workflows.
  • How it Works
  • Workflow Engine Architecture
  • Workflow Builder
  • Rules SDK
  • Key Concepts of the Workflow Engine
Building Blocks
Building Blocks
Packages & Modules
All UI Components
Workflows
Settings
Interface Contracts
All Rules
By Type
All Types
Knowledge Tracks
Extend Knowledge
Glossary
All How-to Guides
Sitemap
Topics
Use Cases
Helpful Resources
Platform Limits
Support Policy
Service Level Agreement (SLA) - Enterprise
Deprecation Policy
Extend Knowledge Content – Terms and Conditions
System and Organization Controls (SOC) 3 Report
Data Privacy Addendum
Security Policy
Quick Links
For Partners
Customer Resources
Webinars and Events
Certifications
Training Resources
Knowledge Tracks
Builders Portal
Product Update Newsletter
Industry Blogs & Events Newsletter
Trust Center Portal

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.

Fluent Logo