How Dynamic Utilities work

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Topic

Author:

Kirill Gaiduk

Changed on:

10 July 2025

Overview

The articles below will walk you through the Dynamic Utilities (`dynamic-core`), designed to simplify rule development and reduce repetitive code.PrerequisitesBefore diving in, make sure you have:

A basic understanding of the Utility Bundles and Dynamic Bundles
Familiarity with writing Rules using the Rules SDK
Completed the Getting Started with the Utility Bundles guide

Author:

Kirill Gaiduk

Changed on:

11 Nov 2025

Overview

The `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

Key points

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.

Java Docs

The helper methods contained in the Utility Bundles libraries are many and varied, so the JavaDocs provided with the packages should be treated as the source of truth for documentation.

Value Proposition

The primary value of the Dynamic Utilities is flexibility.

Configurable Rules: Workflow designers can change what data a Rule fetches or updates by modifying Rule properties, without needing a developer to write and deploy new code.
Reusable Logic: You can create a single, generic rule (e.g., "SetEntityField") that can be used across many different entity types and scenarios, reducing code duplication.
Adaptive Workflows: Build workflows that can adapt to different conditions at runtime by dynamically querying or updating the data that matters most in a given context.

Apollo Android Context

The Fluent Rules SDK relies on Apollo Android to execute GraphQL queries. Apollo's method of pre-compiling queries into Java classes:

Enhances type safety
And boosts performance

However, it also has drawbacks:

Pre-compiled queries restrict Workflow designers from dynamically accessing or updating data, as they require new queries to be developed and compiled each time.
Additionally, the pre-compilation process limits the ability to create universal Rules that apply similar logic across different entity types.

The Dynamic Utilities work around these limitations and enhance Rule configurability.

Explanation through an Example

Here's how Dynamic Utilities solve the Apollo limitation by creating a single, reusable rule that can update any field on any entity:

1package com.fluentcommerce.sample1.test;
2
3import com.fluentcommerce.util.dynamic.graphql.DynamicUpdateMutation;
4import com.fluentretail.rubix.v2.context.Context;
5import com.fluentretail.rubix.v2.rule.Rule;
6import com.fluentretail.rubix.rule.meta.ParamString;
7import com.fluentretail.rubix.rule.meta.RuleInfo;
8import com.google.common.collect.ImmutableMap;
9import lombok.extern.slf4j.Slf4j;
10
11import java.util.Map;
12
13/**
14 * This rule updates a field with a new value.
15 */
16@RuleInfo(name = "UpdateField", description = "Set a field {fieldName} to a value {fieldValue}")
17@Slf4j
18@ParamString(name = "fieldName", description = "Name of the field to be updated")
19@ParamString(name = "fieldValue", description = "New value")
20public class UpdateField implements Rule {
21    @Override
22    public void run(final Context context) {
23        // Get a field to update from rule properties and its new value
24        final String fieldName = context.getProp("fieldName");
25        final String fieldValue = context.getProp("fieldValue");
26
27        // Create a simple map with the field update
28        final Map<String, Object> updates = ImmutableMap.of(fieldName, fieldValue);
29
30        // Use dynamic update mutation to update an entity
31        // This works for ANY entity type without pre-compiled queries
32        context.action().mutation(new DynamicUpdateMutation(context, updates), fieldValue);
33    }
34}

The given example is one of the use cases.

The Dynamic Utilities are flexible and can be used in a wide range of the Rule writing scenarios.The most common ones are provided below.

Overview

Key points

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.

Key Advantages Over Traditional Apollo Queries

One Query, Many Types
`DynamicEntityQuery` allows a single query to be applied across different entities, especially those with common interfaces, removing the need for individual, pre-compiled queries for each entity type. This flexibility reduces the need for branching logic within rules, which can be a major source of inefficiency.
For example, the `ChangeStateGQL` rule became outdated quickly whenever new entity types were introduced. Therefore the `SetState` was introduced which is entity type agnostic and therefore provides more flexibility.
Runtime Query Building
`DynamicEntityQuery` supports building queries at runtime rather than relying solely on pre-compilation. This means that a rule can dynamically determine which data it requires based on parameters or other runtime information.
Reduced Maintenance
No need for individual pre-compiled queries for each entity type, eliminating the overhead of maintaining separate query files and reducing the risk of inconsistencies.

Core Components

`DynamicUtils`: The main utility class that provides a simplified API for all dynamic operations:
- Query Operations: Type-based and path-based querying
- Connection Handling: Paginated data retrieval
- Mutations: Dynamic entity updates
- Data Access: Unified event and entity data access
`DynamicEntityQuery`: The underlying query builder that generates GraphQL queries from:
- POJO class definitions (type-based)
- Path specifications (path-based)
- Query parameters and filters
`DynamicDataTypes`: Provides the response handling mechanisms:
- `QueryDynamicData`: Wrapper for query results with type conversion
- `QueryDynamicVariables`: Variable handling for parameterized queries

Here is a collection of common scenarios for the Dynamic Queries usage:

Type-based usage

To generate a dynamic query from a strongly typed Java class, `DynamicUtils.query()` recursively derives a query based on the fields defined within the class and then executes the query. The resulting object is automatically marshaled back into the same class.

Example 1: Entity Fetching Query

1@lombok.Data
2private static class Sample {
3  String ref;
4  double price;
5}
6
7//Usage 
8Sample sample = DynamicUtils.query(context, Sample.class);

Example 2: Fulfillment Fetching Query

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8// Load Fulfillment
9// This will work in the Context of Fulfillment
10final Fulfilment fulfilment = DynamicUtils.query(context, Fulfilment.class);

Tip

We recommend using Lombok to reduce the overhead of writing these mapping classes, as it can streamline field definitions and boilerplate code.

Benefits:

Type Safety: Strongly typed results with automatic marshaling
Lombok Integration: Use Lombok to reduce boilerplate code
Field Mapping: Only the fields within the class are used for marshaling
Simplified API: `DynamicUtils.query()` handles the complexity of query execution and type conversion

Alternative Direct API Usage

If you need more control over the query execution, you can use the direct API:

1DynamicDataTypes.QueryDynamicData result = (DynamicDataTypes.QueryDynamicData) context.api()
2    .query(new DynamicEntityQuery(context, Sample.class));
3Sample sample = result.as(Sample.class);

Path-based usage

Path-based queries allow you to define your query as a series of strings, where each string represents a dot-separated path through the data graph. This approach is highly flexible and enables the creation of rules that adapt seamlessly to multiple entity types and fields.

Example 1: Multiple-Fields Query

1// Define paths as strings
2ImmutableList.of(
3    "ref",
4    "price", 
5    "items.product.name"
6);

These paths would generate a GraphQL query that retrieves only the specified fields:

1query {
2  order { // root query is determined by the event context
3    ref
4    price
5    items {
6      edges {
7        node {
8          product {
9            name
10          }
11        }
12      }
13    }
14  }
15}
16

The library uses GraphQL schema introspection to ensure that each generated path aligns with valid schema fields; any invalid or mismatched paths are automatically excluded, ensuring that only valid data is queried.

Note

Because the connection pattern is so common in the GraphQL API, you don’t need to specify each level explicitly. For instance, `items.product.name` will automatically expand to `items.edges.node.product.name`.

The resulting `DynamicEntityQuery.DynamicData` object can be accessed either as a Jackson `JsonNode` for structured JSON handling or flattened into a map of graph selectors to `JsonNode` values for quick lookup.

1DynamicDataTypes.QueryDynamicData result = DynamicUtils.query(context, 
2    ImmutableList.of("ref", "price", "items.product.name"));
3
4// Access results using flattened selectors
5ImmutableMap<String, JsonNode> flatResult = result.flat();
6assertEquals("TestProduct", flatResult.get("items[0].product.name").toString());
7
8// Or access individual fields directly
9JsonNode ref = result.get("ref");
10JsonNode price = result.get("price");

Example 2: Single-Field Query

You can also use `DynamicUtils.query` to retrieve a single field value directly from the entity:

1// Get a deliveryType of a fulfilment as TEXT
2// This will work in the Context of Fulfillment
3final String deliveryType = DynamicUtils.query(context, 
4    ImmutableList.of("deliveryType")).get("deliveryType").asText();

Benefits:

Automatic Connection Handling: `items.product.name` automatically expands to `items.edges.node.product.name`
Schema Validation: Uses GraphQL introspection to ensure valid paths
Flexible Access: Results can be accessed as `JsonNode` or flattened map
Error Prevention: Invalid paths are automatically excluded

Connection Queries (Pagination)

For handling paginated connections like `items`, `fulfilments`, etc., use the `queryList()` methods:

Example 1: Specific Fulfillments Loading

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8final Map<String, Object> parameters = new HashMap<>();
9final Map<String, Object> quantity = new HashMap<>();
10quantity.put("filledQuantity", 1);
11quantity.put("rejectedQuantity", 0);
12parameters.put("fulfilments.items", quantity);
13
14// This will work in the Context of Order
15Iterable<Fulfilment> fulfilments = DynamicUtils.queryList(
16    context, 
17    "fulfilments.items", 
18    Fulfilment.class, 
19    parameters
20);
21
22// Process each fulfilment
23for (Fulfilment fulfilment : fulfilments) {
24    // Handle each fulfilment
25}

Example 2: Order Fulfillments Loading

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8// Load all fulfilments of the order
9// This will work in the Context of Order
10final List<Fulfilment> fulfilments = new ArrayList<>();
11Iterable<Fulfilment> fulfilmentIterable = DynamicUtils.queryList(context, "fulfilments", Fulfilment.class, null);
12fulfilmentIterable.forEach(fulfilments::add);

Example 3: Fulfillment Articles Loading

1@lombok.Data
2public class Article {
3    String id;
4    String ref;
5    String name;
6    String type;
7    String status;
8}
9
10// Load all articles of the fulfilment
11// This will work in the Context of Order
12final Map<String, Object> parameters = new HashMap<>();
13parameters.put("id", fulfilment.getId());
14Iterable<Article> articles = DynamicUtils
15        .queryList(context,  "fulfilment", "articles", Article.class, parameters);
16fulfilment.setArticles(new ArrayList<>());
17articles.forEach(fulfilment.getArticles()::add);

Dynamic Mutations

The `DynamicUtils.mutate()` method allows you to update entity properties dynamically:

1Map<String, Object> updates = ImmutableMap.of(
2    "tag1", "ecom",
3    "attributes", ImmutableMap.of(
4        "processedBy", "system",
5        "processedAt", "2024-01-15T10:30:00Z"
6    )
7);
8
9DynamicUtils.mutate(context, updates);

JSON Path Access

The `getJsonPath()` method allows you to access data from either the event or entity using a unified path syntax:

1// Access event data
2JsonNode eventValue = DynamicUtils.getJsonPath(context, "event.attributes.orderType");
3
4// Access entity data  
5JsonNode entityValue = DynamicUtils.getJsonPath(context, "fulfilmentChoice.deliveryType");

Complete Examples

Example 1: Attribute Checking Rule

This rule loads attributes associated with an order and checks if a specified attribute exists:

1package com.example.rule;
2
3import com.fluentcommerce.dto.common.Attribute;
4import com.fluentcommerce.util.core.EventUtils;
5import com.fluentcommerce.util.dynamic.DynamicUtils;
6import com.fluentretail.rubix.rule.meta.EventInfo;
7import com.fluentretail.rubix.rule.meta.EventInfoVariables;
8import com.fluentretail.rubix.rule.meta.ParamString;
9import com.fluentretail.rubix.rule.meta.RuleInfo;
10import com.fluentretail.rubix.v2.context.Context;
11import com.fluentretail.rubix.v2.rule.Rule;
12
13import javax.annotation.Nullable;
14import java.util.List;
15
16import static java.util.Collections.emptyList;
17
18@RuleInfo(
19    name = "IfAttributeExists",
20    description = "If attribute {attributeName} exists, do {eventName}",
21    accepts = { @EventInfo(entityType = "ORDER") },
22    produces = { @EventInfo(
23        eventName = "{eventName}", 
24        entityType = EventInfoVariables.EVENT_TYPE, 
25        entitySubtype = EventInfoVariables.EVENT_SUBTYPE) 
26    }
27)
28@ParamString(name = "attributeName", array = true, description = "Name of the attribute to check")
29@ParamString(name = "eventName", description = "Name of the event to send")
30public class IfAttributeExists implements Rule {
31    @Override
32    public void run(Context context) {
33        String attributeName = context.getProp("attributeName");
34        Entity entity = DynamicUtils.query(context, Entity.class);
35
36        List<Attribute> attributes = entity.getAttributes() != null ? entity.getAttributes() : emptyList();
37        if (attributes.stream().anyMatch(attribute -> attribute.getName().equalsIgnoreCase(attributeName))) {
38            EventUtils.forwardInboundEventWithNewName(context, context.getProp("eventName"));
39        }
40    }
41
42    @lombok.Data
43    public static class Entity {
44        private String id;
45        private String status;
46        @Nullable
47        private List<Attribute> attributes;
48    }
49}

1{
2    "name": "example.orders.IfAttributeExists",
3    "props": {
4        "attributeName": "fcOrderStatusHistory",
5        "eventName": "CompleteOrder"
6    }
7}

Example 2: Flexible Property Comparison

This rule compares a parameter value against an arbitrary field of the primary entity:

1import com.fasterxml.jackson.databind.JsonNode;
2import com.fluentcommerce.util.core.JsonUtils;
3import com.fluentretail.rubix.rule.meta.EventInfo;
4import com.fluentretail.rubix.rule.meta.ParamString;
5import com.fluentretail.rubix.rule.meta.RuleInfo;
6import com.fluentretail.rubix.v2.context.Context;
7import com.fluentretail.rubix.v2.rule.Rule;
8
9import static com.fluentcommerce.util.core.EventUtils.forwardInboundEventWithNewName;
10import static com.fluentcommerce.util.core.LogUtils.logOnce;
11import static com.fluentcommerce.util.dynamic.DynamicUtils.getJsonPath;
12
13@RuleInfo(
14    name = "IfPropertyEquals", 
15    description = "If {jsonpath} is {value}, do {eventName}",
16    produces = { @EventInfo(eventName = "{eventName}") }
17)
18@ParamString(name = "jsonpath", description = "Property of the entity, e.g. 'fulfilmentChoice.deliveryType'")
19@ParamString(name = "value", description = "Value to compare, e.g. 'EXPRESS'")
20@ParamString(name = "eventName", description = "Name of the event to send")
21public class IfPropertyEquals implements Rule {
22    @Override
23    public void run(Context context) {
24        String jsonPath = context.getProp("jsonpath");
25        String value = context.getProp("value");
26
27        JsonNode result = DynamicUtils.getJsonPath(context, jsonPath);
28
29        if (JsonUtils.marshallAndEquals(value, result)) {
30            forwardInboundEventWithNewName(context, context.getProp("eventName"));
31        } else {
32            logOnce(context, IfPropertyEquals.class, "Values '%s' and '%s' are not equal", result, value);
33        }
34    }
35}

Note

This example uses some methods from the Core Utilities.

1{
2  "name": "example.core.IfPropertyEquals",
3  "props": {
4	"jsonpath": "fulfilmentChoice.shippingType",
5    "value": "EXPRESS",
6    "eventName": "SourceOrderForExpressDelivery"
7  }
8}

Recommended Practices

Use Lombok: Reduce boilerplate code for mapping classes
Type Safety: Prefer type-based queries when possible for better compile-time safety
Path Validation: Use path-based queries when field selection needs to be configurable
Error Handling: Always check for null results when accessing nested properties
Performance: Only query the fields you need to minimize data transfer

Overview

`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.

Key points

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.

Note

The GraphQL mutation used to persist the data is selected automatically from the `RulesetContext` based on the entity type (e.g., `updateConsignment`). Custom mutations cannot be specified directly; the mutation is always determined by the Context.

Here is a collection of common scenarios for the Dynamic Mutations usage:

Field-based Updates

Fields can be updated directly by name. You can:

Update a single field
Provide multiple fields in a `Map<String, Object>` for bulk updates

1context.action().mutation(
2    new DynamicUpdateMutation(context, "status", context.getProp("status"))
3);

1context.action().mutation(
2  new DynamicUpdateMutation(context, ImmutableMap.of(
3    "status", context.getProp("status"),
4    "attributes", Attribute.of("New Attribute", "New Value")
5  )));

Type-based Update

For improved type safety, `DynamicUpdateMutation` can also recursively derive update fields from a defined POJO. This allows you to work with strongly typed objects while still benefiting from dynamic field updates, ensuring both flexibility and safety in your Rule logic.

1@lombok.Data
2@lombok.AllArgsConstructor
3private static class Sample {
4    String status;
5    List<Attribute> attributes;
6}
7
8// Create the update object
9Sample sample = new Sample(
10    context.getProp("status"), 
11    Attribute.of("New Attribute", "New Value")
12);
13
14// Execute the mutation
15context.action().mutation(new DynamicUpdateMutation(context, sample));

Error Handling

The `DynamicUpdateMutation` provides built-in error handling:

1// Strict validation - throws exception for invalid fields
2new DynamicUpdateMutation(context, updates, true);
3
4// Lenient validation - silently excludes invalid fields
5new DynamicUpdateMutation(context, updates, false);

This ensures that your mutations are robust and handle edge cases gracefully.

Complete Examples

Example 1: Generic Field Setter Rule

This rule demonstrates how to create a reusable field setter that works for any entity type:

1import com.fluentcommerce.util.dynamic.DynamicUtils;
2import com.fluentretail.rubix.rule.meta.ParamString;
3import com.fluentretail.rubix.rule.meta.RuleInfo;
4import com.fluentretail.rubix.v2.context.Context;
5import com.fluentretail.rubix.v2.rule.Rule;
6
7import java.util.Map;
8
9@RuleInfo(
10    name = "SetEntityField",
11    description = "Set field {fieldName} to {fieldValue} on the current entity"
12)
13@ParamString(name = "fieldName", description = "Name of the field to update")
14@ParamString(name = "fieldValue", description = "Value to set for the field")
15public class SetEntityField implements Rule {
16    @Override
17    public void run(Context context) {
18        String fieldName = context.getProp("fieldName");
19        String fieldValue = context.getProp("fieldValue");
20        
21        // Create a simple map with the field update
22        Map<String, Object> updates = Map.of(fieldName, fieldValue);
23        
24        // Use DynamicUtils for cleaner syntax
25        DynamicUtils.mutate(context, updates);
26    }
27}

1{
2    "name": "example.core.SetEntityField",
3    "props": {
4        "fieldName": "tag1",
5        "fieldValue": "newTag"
6    }
7}

Example 2: Complex Object Update

This example shows how to update complex nested objects using type-based mutations:

1import com.fluentcommerce.dto.common.Attribute;
2import com.fluentcommerce.util.dynamic.DynamicUtils;
3import com.fluentretail.rubix.rule.meta.EventInfo;
4import com.fluentretail.rubix.rule.meta.ParamString;
5import com.fluentretail.rubix.rule.meta.RuleInfo;
6import com.fluentretail.rubix.v2.context.Context;
7import com.fluentretail.rubix.v2.rule.Rule;
8
9import java.util.List;
10
11@RuleInfo(
12    name = "UpdateOrderWithAttributes",
13    description = "Update order tag1 and add custom attributes",
14    accepts = { @EventInfo(entityType = "ORDER") }
15)
16@ParamString(name = "tag1", description = "New tag 1 for the order")
17@ParamString(name = "attributeName", description = "Name of the attribute to add")
18@ParamString(name = "attributeValue", description = "Value of the attribute to add")
19public class UpdateOrderWithAttributes implements Rule {
20    @Override
21    public void run(Context context) {
22        String tag1 = context.getProp("tag1");
23        String attributeName = context.getProp("attributeName");
24        String attributeValue = context.getProp("attributeValue");
25        
26        // Create a typed update object
27        OrderUpdate update = new OrderUpdate(
28            tag1,
29            List.of(Attribute.of(attributeName, attributeValue))
30        );
31        
32        // Execute the mutation
33        context.action().mutation(new DynamicUpdateMutation(context, update));
34    }
35    
36    @lombok.Data
37    @lombok.AllArgsConstructor
38    private static class OrderUpdate {
39        private String tag1;
40        private List<Attribute> attributes;
41    }
42}

Best Practices

Use DynamicUtils: Prefer `DynamicUtils.mutate()` for simpler syntax when possible
Type Safety: Use POJO classes for complex updates to ensure field validity
Error Handling: Set `errorOnInvalidVariables` to true for strict validation
Logging: Always log mutations for auditing and debugging purposes
Validation: Validate input values before passing them to mutations

Overview

Key points

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.

Note

The GraphQL query used to fetch the data is selected automatically from the `RulesetContext` based on the Entity type (e.g., `consignmentById`). However, you can also specify a preferred Query using a Utility method.

Here is a collection of common scenarios for the Dynamic Pagination usage:

Query from Context usage

The simplest approach is to let the system automatically select the appropriate GraphQL query based on the entity type from the `RulesetContext`.

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8// Load all Order Fulfilments with status COMPLETE
9final List<Fulfilment> fulfilments = new ArrayList<>();
10final Iterable<Fulfilment> iterable = DynamicUtils.queryList(context,
11    "fulfilments", Fulfilment.class,
12    Collections.singletonMap("fulfilments", Collections.singletonMap("status", "COMPLETE")));
13orderItemIterable.forEach(fulfilments::add);

Explanation through an Example

The rule loads the attributes associated with an order and checks if attribute with specified name exists. If the condition is met, the rule sends an event.

1package com.example.rule; 
2  
3import com.fluentcommerce.util.core.EventUtils;
4import com.fluentcommerce.util.dynamic.DynamicUtils;
5import com.fluentretail.rubix.rule.meta.*;
6import com.fluentretail.rubix.v2.context.Context;
7import com.fluentretail.rubix.v2.rule.Rule;
8import java.util.List;
9import java.util.stream.Stream;
10import java.util.stream.StreamSupport;
11
12@RuleInfo(
13        name = "IfAllFulfilmentsInState",
14        description = "If all fulfilments are in status {status}, do {eventName}",
15        accepts = { @EventInfo(entityType = "ORDER") },
16        produces = { @EventInfo(eventName = "{eventName}", entityType = "ORDER", entitySubtype = EventInfoVariables.EVENT_SUBTYPE, status = EventInfoVariables.EVENT_STATUS) }
17)
18@ParamString(name = "status", array = true, description = "List of statuses to check")
19@ParamString(name = "eventName", description = "Name of the event to send")
20public class IfAllFulfilmentsInState implements Rule {
21    @Override
22    public void run(Context context) {
23        List<String> states = context.getPropList("status", String.class);
24
25        Iterable<Fulfilment> fulfilmentIterable = DynamicUtils.queryList(context, "fulfilments",
26                Fulfilment.class, null);
27        Stream<Fulfilment> fulfilmentStream = StreamSupport.stream(fulfilmentIterable.spliterator(), false);
28
29        if(fulfilmentStream.allMatch(f -> states.contains(f.status))) {
30            EventUtils.forwardInboundEventWithNewName(context, context.getProp("eventName"));
31        }
32    }
33
34    @lombok.Data
35    public static class Fulfilment {
36        String status;
37    }
38}

Note

This example uses some methods from the Core Utilities.

1{
2  "name": "example.orders.IfAllFulfilmentsInState",
3  "props": {
4    "status": [ "COMPLETE", "CANCELLED" ],
5    "eventName": "CompleteOrder"
6  }
7}

Query from Parameter usage

Alternatively, you can explicitly specify the GraphQL query within the method, giving you more control over the query selection. This approach allows for greater flexibility when you need to handle different types of queries within the same rule.

1@lombok.Data
2public class OrderItem {
3    String id;
4    String ref;
5    Double price;
6}
7
8//Get Order Items By Order Id
9final List<OrderItem> orderItems = new ArrayList<>();
10Iterable<OrderItem> orderItemIterable = DynamicUtils.queryList(context, 
11    "order", "items", OrderItem.class,
12    Collections.singletonMap("id", orderId));
13orderItemIterable.forEach(orderItems::add);

Overview

Key points

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.

Key Advantages Over Traditional Apollo Queries

One Query, Many Types
`DynamicEntityQuery` allows a single query to be applied across different entities, especially those with common interfaces, removing the need for individual, pre-compiled queries for each entity type. This flexibility reduces the need for branching logic within rules, which can be a major source of inefficiency.
For example, the `ChangeStateGQL` rule became outdated quickly whenever new entity types were introduced. Therefore the `SetState` was introduced which is entity type agnostic and therefore provides more flexibility.
Runtime Query Building
`DynamicEntityQuery` supports building queries at runtime rather than relying solely on pre-compilation. This means that a rule can dynamically determine which data it requires based on parameters or other runtime information.
Reduced Maintenance
No need for individual pre-compiled queries for each entity type, eliminating the overhead of maintaining separate query files and reducing the risk of inconsistencies.

Core Components

`DynamicUtils`: The main utility class that provides a simplified API for all dynamic operations:
- Query Operations: Type-based and path-based querying
- Connection Handling: Paginated data retrieval
- Mutations: Dynamic entity updates
- Data Access: Unified event and entity data access
`DynamicEntityQuery`: The underlying query builder that generates GraphQL queries from:
- POJO class definitions (type-based)
- Path specifications (path-based)
- Query parameters and filters
`DynamicDataTypes`: Provides the response handling mechanisms:
- `QueryDynamicData`: Wrapper for query results with type conversion
- `QueryDynamicVariables`: Variable handling for parameterized queries

Here is a collection of common scenarios for the Dynamic Queries usage:

Type-based usage

Example 1: Entity Fetching Query

1@lombok.Data
2private static class Sample {
3  String ref;
4  double price;
5}
6
7//Usage 
8Sample sample = DynamicUtils.query(context, Sample.class);

Example 2: Fulfillment Fetching Query

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8// Load Fulfillment
9// This will work in the Context of Fulfillment
10final Fulfilment fulfilment = DynamicUtils.query(context, Fulfilment.class);

Tip

We recommend using Lombok to reduce the overhead of writing these mapping classes, as it can streamline field definitions and boilerplate code.

Benefits:

Type Safety: Strongly typed results with automatic marshaling
Lombok Integration: Use Lombok to reduce boilerplate code
Field Mapping: Only the fields within the class are used for marshaling
Simplified API: `DynamicUtils.query()` handles the complexity of query execution and type conversion

Alternative Direct API Usage

If you need more control over the query execution, you can use the direct API:

1DynamicDataTypes.QueryDynamicData result = (DynamicDataTypes.QueryDynamicData) context.api()
2    .query(new DynamicEntityQuery(context, Sample.class));
3Sample sample = result.as(Sample.class);

Path-based usage

Example 1: Multiple-Fields Query

1// Define paths as strings
2ImmutableList.of(
3    "ref",
4    "price", 
5    "items.product.name"
6);

These paths would generate a GraphQL query that retrieves only the specified fields:

1query {
2  order { // root query is determined by the event context
3    ref
4    price
5    items {
6      edges {
7        node {
8          product {
9            name
10          }
11        }
12      }
13    }
14  }
15}
16

Note

1DynamicDataTypes.QueryDynamicData result = DynamicUtils.query(context, 
2    ImmutableList.of("ref", "price", "items.product.name"));
3
4// Access results using flattened selectors
5ImmutableMap<String, JsonNode> flatResult = result.flat();
6assertEquals("TestProduct", flatResult.get("items[0].product.name").toString());
7
8// Or access individual fields directly
9JsonNode ref = result.get("ref");
10JsonNode price = result.get("price");

Example 2: Single-Field Query

You can also use `DynamicUtils.query` to retrieve a single field value directly from the entity:

1// Get a deliveryType of a fulfilment as TEXT
2// This will work in the Context of Fulfillment
3final String deliveryType = DynamicUtils.query(context, 
4    ImmutableList.of("deliveryType")).get("deliveryType").asText();

Benefits:

Automatic Connection Handling: `items.product.name` automatically expands to `items.edges.node.product.name`
Schema Validation: Uses GraphQL introspection to ensure valid paths
Flexible Access: Results can be accessed as `JsonNode` or flattened map
Error Prevention: Invalid paths are automatically excluded

Connection Queries (Pagination)

For handling paginated connections like `items`, `fulfilments`, etc., use the `queryList()` methods:

Example 1: Specific Fulfillments Loading

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8final Map<String, Object> parameters = new HashMap<>();
9final Map<String, Object> quantity = new HashMap<>();
10quantity.put("filledQuantity", 1);
11quantity.put("rejectedQuantity", 0);
12parameters.put("fulfilments.items", quantity);
13
14// This will work in the Context of Order
15Iterable<Fulfilment> fulfilments = DynamicUtils.queryList(
16    context, 
17    "fulfilments.items", 
18    Fulfilment.class, 
19    parameters
20);
21
22// Process each fulfilment
23for (Fulfilment fulfilment : fulfilments) {
24    // Handle each fulfilment
25}

Example 2: Order Fulfillments Loading

1@lombok.Data
2public class Fulfilment {
3    String id;
4    String ref;
5    String type;
6}
7
8// Load all fulfilments of the order
9// This will work in the Context of Order
10final List<Fulfilment> fulfilments = new ArrayList<>();
11Iterable<Fulfilment> fulfilmentIterable = DynamicUtils.queryList(context, "fulfilments", Fulfilment.class, null);
12fulfilmentIterable.forEach(fulfilments::add);

Example 3: Fulfillment Articles Loading

1@lombok.Data
2public class Article {
3    String id;
4    String ref;
5    String name;
6    String type;
7    String status;
8}
9
10// Load all articles of the fulfilment
11// This will work in the Context of Order
12final Map<String, Object> parameters = new HashMap<>();
13parameters.put("id", fulfilment.getId());
14Iterable<Article> articles = DynamicUtils
15        .queryList(context,  "fulfilment", "articles", Article.class, parameters);
16fulfilment.setArticles(new ArrayList<>());
17articles.forEach(fulfilment.getArticles()::add);

Dynamic Mutations

The `DynamicUtils.mutate()` method allows you to update entity properties dynamically:

1Map<String, Object> updates = ImmutableMap.of(
2    "tag1", "ecom",
3    "attributes", ImmutableMap.of(
4        "processedBy", "system",
5        "processedAt", "2024-01-15T10:30:00Z"
6    )
7);
8
9DynamicUtils.mutate(context, updates);

JSON Path Access

The `getJsonPath()` method allows you to access data from either the event or entity using a unified path syntax:

1// Access event data
2JsonNode eventValue = DynamicUtils.getJsonPath(context, "event.attributes.orderType");
3
4// Access entity data  
5JsonNode entityValue = DynamicUtils.getJsonPath(context, "fulfilmentChoice.deliveryType");

Complete Examples

Example 1: Attribute Checking Rule

This rule loads attributes associated with an order and checks if a specified attribute exists:

1package com.example.rule;
2
3import com.fluentcommerce.dto.common.Attribute;
4import com.fluentcommerce.util.core.EventUtils;
5import com.fluentcommerce.util.dynamic.DynamicUtils;
6import com.fluentretail.rubix.rule.meta.EventInfo;
7import com.fluentretail.rubix.rule.meta.EventInfoVariables;
8import com.fluentretail.rubix.rule.meta.ParamString;
9import com.fluentretail.rubix.rule.meta.RuleInfo;
10import com.fluentretail.rubix.v2.context.Context;
11import com.fluentretail.rubix.v2.rule.Rule;
12
13import javax.annotation.Nullable;
14import java.util.List;
15
16import static java.util.Collections.emptyList;
17
18@RuleInfo(
19    name = "IfAttributeExists",
20    description = "If attribute {attributeName} exists, do {eventName}",
21    accepts = { @EventInfo(entityType = "ORDER") },
22    produces = { @EventInfo(
23        eventName = "{eventName}", 
24        entityType = EventInfoVariables.EVENT_TYPE, 
25        entitySubtype = EventInfoVariables.EVENT_SUBTYPE) 
26    }
27)
28@ParamString(name = "attributeName", array = true, description = "Name of the attribute to check")
29@ParamString(name = "eventName", description = "Name of the event to send")
30public class IfAttributeExists implements Rule {
31    @Override
32    public void run(Context context) {
33        String attributeName = context.getProp("attributeName");
34        Entity entity = DynamicUtils.query(context, Entity.class);
35
36        List<Attribute> attributes = entity.getAttributes() != null ? entity.getAttributes() : emptyList();
37        if (attributes.stream().anyMatch(attribute -> attribute.getName().equalsIgnoreCase(attributeName))) {
38            EventUtils.forwardInboundEventWithNewName(context, context.getProp("eventName"));
39        }
40    }
41
42    @lombok.Data
43    public static class Entity {
44        private String id;
45        private String status;
46        @Nullable
47        private List<Attribute> attributes;
48    }
49}

1{
2    "name": "example.orders.IfAttributeExists",
3    "props": {
4        "attributeName": "fcOrderStatusHistory",
5        "eventName": "CompleteOrder"
6    }
7}

Example 2: Flexible Property Comparison

This rule compares a parameter value against an arbitrary field of the primary entity:

1import com.fasterxml.jackson.databind.JsonNode;
2import com.fluentcommerce.util.core.JsonUtils;
3import com.fluentretail.rubix.rule.meta.EventInfo;
4import com.fluentretail.rubix.rule.meta.ParamString;
5import com.fluentretail.rubix.rule.meta.RuleInfo;
6import com.fluentretail.rubix.v2.context.Context;
7import com.fluentretail.rubix.v2.rule.Rule;
8
9import static com.fluentcommerce.util.core.EventUtils.forwardInboundEventWithNewName;
10import static com.fluentcommerce.util.core.LogUtils.logOnce;
11import static com.fluentcommerce.util.dynamic.DynamicUtils.getJsonPath;
12
13@RuleInfo(
14    name = "IfPropertyEquals", 
15    description = "If {jsonpath} is {value}, do {eventName}",
16    produces = { @EventInfo(eventName = "{eventName}") }
17)
18@ParamString(name = "jsonpath", description = "Property of the entity, e.g. 'fulfilmentChoice.deliveryType'")
19@ParamString(name = "value", description = "Value to compare, e.g. 'EXPRESS'")
20@ParamString(name = "eventName", description = "Name of the event to send")
21public class IfPropertyEquals implements Rule {
22    @Override
23    public void run(Context context) {
24        String jsonPath = context.getProp("jsonpath");
25        String value = context.getProp("value");
26
27        JsonNode result = DynamicUtils.getJsonPath(context, jsonPath);
28
29        if (JsonUtils.marshallAndEquals(value, result)) {
30            forwardInboundEventWithNewName(context, context.getProp("eventName"));
31        } else {
32            logOnce(context, IfPropertyEquals.class, "Values '%s' and '%s' are not equal", result, value);
33        }
34    }
35}

Note

This example uses some methods from the Core Utilities.

1{
2  "name": "example.core.IfPropertyEquals",
3  "props": {
4	"jsonpath": "fulfilmentChoice.shippingType",
5    "value": "EXPRESS",
6    "eventName": "SourceOrderForExpressDelivery"
7  }
8}

Recommended Practices

Use Lombok: Reduce boilerplate code for mapping classes
Type Safety: Prefer type-based queries when possible for better compile-time safety
Path Validation: Use path-based queries when field selection needs to be configurable
Error Handling: Always check for null results when accessing nested properties
Performance: Only query the fields you need to minimize data transfer

Overview

`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.

Key points

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.

Note

Here is a collection of common scenarios for the Dynamic Mutations usage:

Field-based Updates

Fields can be updated directly by name. You can:

Update a single field
Provide multiple fields in a `Map<String, Object>` for bulk updates

1context.action().mutation(
2    new DynamicUpdateMutation(context, "status", context.getProp("status"))
3);

1context.action().mutation(
2  new DynamicUpdateMutation(context, ImmutableMap.of(
3    "status", context.getProp("status"),
4    "attributes", Attribute.of("New Attribute", "New Value")
5  )));

Type-based Update

1@lombok.Data
2@lombok.AllArgsConstructor
3private static class Sample {
4    String status;
5    List<Attribute> attributes;
6}
7
8// Create the update object
9Sample sample = new Sample(
10    context.getProp("status"), 
11    Attribute.of("New Attribute", "New Value")
12);
13
14// Execute the mutation
15context.action().mutation(new DynamicUpdateMutation(context, sample));

Error Handling

The `DynamicUpdateMutation` provides built-in error handling:

1// Strict validation - throws exception for invalid fields
2new DynamicUpdateMutation(context, updates, true);
3
4// Lenient validation - silently excludes invalid fields
5new DynamicUpdateMutation(context, updates, false);

This ensures that your mutations are robust and handle edge cases gracefully.

Complete Examples

Example 1: Generic Field Setter Rule

This rule demonstrates how to create a reusable field setter that works for any entity type:

1import com.fluentcommerce.util.dynamic.DynamicUtils;
2import com.fluentretail.rubix.rule.meta.ParamString;
3import com.fluentretail.rubix.rule.meta.RuleInfo;
4import com.fluentretail.rubix.v2.context.Context;
5import com.fluentretail.rubix.v2.rule.Rule;
6
7import java.util.Map;
8
9@RuleInfo(
10    name = "SetEntityField",
11    description = "Set field {fieldName} to {fieldValue} on the current entity"
12)
13@ParamString(name = "fieldName", description = "Name of the field to update")
14@ParamString(name = "fieldValue", description = "Value to set for the field")
15public class SetEntityField implements Rule {
16    @Override
17    public void run(Context context) {
18        String fieldName = context.getProp("fieldName");
19        String fieldValue = context.getProp("fieldValue");
20        
21        // Create a simple map with the field update
22        Map<String, Object> updates = Map.of(fieldName, fieldValue);
23        
24        // Use DynamicUtils for cleaner syntax
25        DynamicUtils.mutate(context, updates);
26    }
27}

1{
2    "name": "example.core.SetEntityField",
3    "props": {
4        "fieldName": "tag1",
5        "fieldValue": "newTag"
6    }
7}

Example 2: Complex Object Update

This example shows how to update complex nested objects using type-based mutations:

1import com.fluentcommerce.dto.common.Attribute;
2import com.fluentcommerce.util.dynamic.DynamicUtils;
3import com.fluentretail.rubix.rule.meta.EventInfo;
4import com.fluentretail.rubix.rule.meta.ParamString;
5import com.fluentretail.rubix.rule.meta.RuleInfo;
6import com.fluentretail.rubix.v2.context.Context;
7import com.fluentretail.rubix.v2.rule.Rule;
8
9import java.util.List;
10
11@RuleInfo(
12    name = "UpdateOrderWithAttributes",
13    description = "Update order tag1 and add custom attributes",
14    accepts = { @EventInfo(entityType = "ORDER") }
15)
16@ParamString(name = "tag1", description = "New tag 1 for the order")
17@ParamString(name = "attributeName", description = "Name of the attribute to add")
18@ParamString(name = "attributeValue", description = "Value of the attribute to add")
19public class UpdateOrderWithAttributes implements Rule {
20    @Override
21    public void run(Context context) {
22        String tag1 = context.getProp("tag1");
23        String attributeName = context.getProp("attributeName");
24        String attributeValue = context.getProp("attributeValue");
25        
26        // Create a typed update object
27        OrderUpdate update = new OrderUpdate(
28            tag1,
29            List.of(Attribute.of(attributeName, attributeValue))
30        );
31        
32        // Execute the mutation
33        context.action().mutation(new DynamicUpdateMutation(context, update));
34    }
35    
36    @lombok.Data
37    @lombok.AllArgsConstructor
38    private static class OrderUpdate {
39        private String tag1;
40        private List<Attribute> attributes;
41    }
42}

Best Practices

Use DynamicUtils: Prefer `DynamicUtils.mutate()` for simpler syntax when possible
Type Safety: Use POJO classes for complex updates to ensure field validity
Error Handling: Set `errorOnInvalidVariables` to true for strict validation
Logging: Always log mutations for auditing and debugging purposes
Validation: Validate input values before passing them to mutations

How Dynamic Utilities work

Overview

Dynamic Utilities Overview

Overview

Key points

Value Proposition

Apollo Android Context

Explanation through an Example

Related content

Dynamic Utilities

How Dynamic Utilities work

Dynamic Queries and Utils

Dynamic Mutations

Dynamic Pagination

Dynamic Queries and Utils

Overview

Key points

Key Advantages Over Traditional Apollo Queries

Core Components

Type-based usage

Example 1: Entity Fetching Query

Example 2: Fulfillment Fetching Query

Alternative Direct API Usage

Path-based usage

Example 1: Multiple-Fields Query

Example 2: Single-Field Query

Connection Queries (Pagination)

Example 1: Specific Fulfillments Loading

Example 2: Order Fulfillments Loading

Example 3: Fulfillment Articles Loading

Dynamic Mutations

JSON Path Access

Complete Examples

Example 1: Attribute Checking Rule

Example 2: Flexible Property Comparison

Related content

Dynamic Utilities Overview

How Dynamic Utilities work

Dynamic Mutations

Dynamic Pagination

Dynamic Mutations

Overview

Key points

Field-based Updates

Type-based Update

Error Handling

Complete Examples

Example 1: Generic Field Setter Rule

Example 2: Complex Object Update

Related content

Dynamic Utilities Overview

How Dynamic Utilities work

Dynamic Queries and Utils

Dynamic Pagination

Dynamic Pagination

Overview

Key points

Query from Context usage

Explanation through an Example

Query from Parameter usage

Related content

Dynamic Utilities Overview

How Dynamic Utilities work

Dynamic Queries and Utils

Dynamic Mutations

Related content

Utility Bundles Overview

Getting Started with the Utility Bundles

How Core Utilities work

How Test Utilities work

Kirill Gaiduk

Building Blocks

By Type

Helpful Resources

Quick Links

Dynamic Utilities Overview

Overview

Key points

Value Proposition

Apollo Android Context