Utility Bundles Overview

The Design Philosophy: From Source Code to Building Blocks

• Simpler Rules: Your Rules become much cleaner and more focused on the business logic, as the overhead of data fetching, transformation, and action creation is handled by the utilities.
• Effortless Upgrades: You can receive new features, bug fixes, and performance improvements by updating the utility dependency version in your `pom.xml`. No more manual merging.

Breaking Down a Rule: How Utilities Help

1. Validation

• Rule Properties: These don't change at runtime, so their validation should be handled by workflow unit tests, not runtime checks. The `RuleUtils` utility helps retrieve them safely.
• Event Attributes: These do change at runtime, so they are excellent candidates for validation within a utility. For rich types, the best approach is to map the attribute directly to a POJO using `JsonUtils`.

2. Data Fetching

• Think Usage: For example, instead of a generic `getOrder(context)` method that would require every Rule to then filter out already fulfilled items, a better utility is `getUnfulfilledItems(context)`, which does that logic for you.

3. Business Logic

• Pass in Functions: A powerful pattern used in the utilities is allowing developers to pass in their own functions to override or extend default behavior. For example, a utility that finds the best fulfillment plan might accept a custom scoring function as a parameter. This makes the utilities flexible building blocks rather than rigid, black-box solutions.
• Identify Archetypes: The utilities are often built to support common Rule "archetypes", such as "Flow Control" rules that conditionally send events, or domain-specific ones like "Fulfillment Strategy" rules.

4. Actions

• Convert Logic to Actions: For example, if a business logic utility returns a list of proposed fulfillments, another utility can take that list and turn it into the required set of `updateFulfilment` mutations.

Why Use Utility Bundles?

• Accelerate Development: Handle common tasks like date formatting, JSON conversion, and event forwarding with single lines of code.
• Improve Code Quality: Leverage pre-built, tested functions that handle common error scenarios and edge cases.
• Simplify Maintenance: Update a utility function in one place, and the change is reflected everywhere it's used.
• Easy Upgrades: Stay current with the latest features and bug fixes from Fluent Commerce by updating the dependency version in your `pom.xml`.

The Utility Bundles

Core Utilities

• Key Classes: `EventUtils`, `SettingUtils`, `QueryUtils`, `RuleUtils`, `JsonUtils`.

Dynamic Utilities

• Key Classes: `DynamicUtils`, an advanced `JsonUtils`.

Test Utilities

• Key Classes: `RuleExecutor`, `WorkflowExecutor`, `MockApiClient`.

A Practical Example: Tracking Status History

1@RuleInfo(name = "UpdateStatusHistory", /*...*/)
2public class UpdateStatusHistory implements Rule {
3
4    // A POJO to represent the entity fields we need
5    // With @Data, 'private' is redundant
6    @Data
7    public static class EntityData {
8        String createdOn;
9        String status;
10        List<Attribute> attributes;
11    }
12
13    @Override
14    public void run(Context context) {
15        // 1. DATA FETCHING: Use DynamicUtils to get only the fields we need
16        EntityData entity = DynamicUtils.query(context, EntityData.class);
17        
18        // Find the existing history attribute from the entity's attributes
19        // (Logic to find attribute by name is omitted for brevity)
20        Optional<Attribute> historyAttribute = findHistoryAttribute(entity.getAttributes());
21        
22        // 2. BUSINESS LOGIC: Deserialize old history, calculate time, add new entry
23        // The list of previous status updates is retrieved from the attribute using JsonUtils
24        List<StatusUpdate> history = getHistoryFromAttribute(historyAttribute);
25        long durationInPreviousStatus = calculateDuration(history, entity.getCreatedOn());
26        history.add(new StatusUpdate(entity.getStatus(), /*...*/));
27        
28        // 3. ACTIONS: Use DynamicUtils to persist the updated attribute list
29        Attribute updatedAttribute = createHistoryAttribute(history);
30        DynamicUtils.mutate(
31            context,
32            ImmutableMap.of("attributes", Collections.singletonList(updatedAttribute))
33        );
34    }
35}