Collection

Configurable properties

collectionSource: This property specifies the process key where a list can be found. It should be a valid array of objects.

Example usage

Here’s an example of configuring a Collection component to display a list of products:

Collection configuration for displaying employees

Source collection data example using an MVEL business rule:

output.put("processData", //this is the key
{
  "products": [ // this is the source that will populate the data on collection
    {
      "name": "Product One Plus",
      "description": "The plus option",
      "type": "normal"
    },
    {
      "name": "Product Two Premium",
      "description": "This is premium product",
      "type": "recommended"
    },
    {
      "name": "Product Basic",
      "description": "The most basic option",
      "type": "normal"
    },
    {
      "name": "Gold Product",
      "description": "The gold option",
      "type": "normal"
    }
  ]
}
);

The above configuration will render the Collection as shown below:

Components within a collection use relative paths to the collection source. This means that wherever the collection is found inside the process data, the components inside the collection need their keys configured relative to that collection.

To send and display dynamic data received on the keys you define to the frontend, make sure to include the following data structure in your root UI element using Message parameters. For instance, if you want to include data for the processData key mentioned earlier, your configuration should resemble this:

{
  "processData": ${processData}
}

When do you need Collection Prototypes?

Single layout for all items: If all items in your collection should display the same way, add one Collection Prototype and leave PIK/PIV empty
Multiple layouts based on item properties: If items should display differently based on their data (like the type field in the example above), add multiple Collection Prototypes with PIK/PIV configured

For detailed configuration guidance, see the Collection Prototype documentation:

Collection prototype

Forms in collections

Forms in Collections is a feature that enables you to create dynamic, repeatable forms within collection prototypes. This eliminates the need for custom development when building forms with repeatable sections like adding multiple co-debtors or comment entries.

Overview

Forms in Collections addresses common pain points in form design:

Dynamic Forms: No longer need custom development to support dynamic forms that show different form elements based on certain conditions
Repeatable Sections: Create forms with repeatable sections like adding co-debtors, comments, or any list of similar items
Flexible Validation: Support both individual item validation and bulk validation scenarios

The feature allows you to drag Form components directly into Collection Prototypes, where they automatically repeat for each item in your data array.

Collection source rules remain the same as regular collections. Each key in collection prototypes uses a prefix computed from the collection source and the index of the object being displayed. At runtime, keys are constructed with the full object path (e.g., application.clients[0].name).

How it works

When you add forms to a collection prototype:

Data Structure: Your process data contains an array of objects (e.g., application.clients)
UI Configuration: Collection component points to your array, and Form components are placed inside Collection Prototypes
Key Generation: Form field keys are automatically prefixed with the collection path and item index
Runtime Behavior: Each collection item gets its own form instance with properly scoped keys

Implementation guide

Prepare your data structure

Set up your process data with an array to hold the repeatable items:

// Define an object named 'application' to store client information
var application = {
    client: {
        // Store the client's name
        name: "Aang the Last Airbender",
        // Store the loan amount details
        loanAmount: {
            amount: 238989, // The loan amount
            code: "USD" // The currency code for the loan amount
        },
        // List of codebtors associated with the loan
        codebtors: [
            {
                // First codebtor's name and occupation
                id: 1,
                name: "Sokka",
                occupation: "Boomerang Master"
            },
            {
                // Second codebtor's name and occupation
                id: 2,
                name: "Prince Zuko",
                occupation: "Firebending Master"
            }
        ]
    }
};

// Output the client information from the application object
output.put("application", { "client": application.client });

Create the Collection component

In the UI Designer, add a Collection component
Set the Collection Source to point to your array (e.g., application.client.codebtors)
The collection will iterate through each item in the array

Add Collection Prototype with Forms

Add a Collection Prototype as a child of your Collection component
Configure prototype identifier. This is the key that will be used to identify the prototype.
Drag Form components directly into the Collection Prototype
Configure form fields with relative keys (e.g., name, email)

This is the key innovation: you can now place Form components directly inside Collection Prototypes, and they will automatically repeat for each collection item.

Configure form fields

Configure each form field using relative paths to the collection item data:

Use keys like name, email, type (not full paths)
The system automatically constructs the full path at runtime
Example: name becomes application.client.codebtors[0].name for the first item

Saving scenarios

Forms in Collections supports two distinct saving approaches, each suited for different use cases:

Individual Item Save (Scenario 1)
Bulk Save (Scenario 2)

When to use: Save one collection item at a time, with validation only for that specific item.Configuration:

Place your Save button inside the Collection Prototype
Configure a Collection Item Save Key on the event handler
The edited object will be saved to this key
Add a business rule to update the original array and send it back to the frontend

Behavior:

Validates only the forms for the specific collection index where the action is triggered
Saves individual items as they are edited
Requires business rule to sync changes back to the main array

You must configure a business rule to update the original array after individual saves to maintain data consistency.

Business rule Examples

Business rule - Add new codebtor in the array

// This business rule is adapted to the runtime requirements of the FlowX.AI engine.

// ARGS
var application = null;
var client = null;

if (input["application"] != null) {
    application = input["application"];
}
if (application != null && application["client"] != null) {
    client = application["client"];
}

// Business Rule Code
if (client != null) {
    if (!Array.isArray(client["codebtors"])) {
        client["codebtors"] = [];
    }
    var newCodebtor = {"name": ""};
    newCodebtor["id"] = client["codebtors"].length + 1;
    client["codebtors"].push(newCodebtor);
}

// OUTPUT
if (client != null) {
    output["application"] = { "client": client };
} else {
    output["error"] = {
        "type": "MISSING_FIELD",
        "message": "Client is missing"
    };
}

Send data to the frontend

{ "application": ${application}}

When to use: Save all collection items at once with validation for all forms.Configuration:

Place your Save button outside the Collection (not in the prototype)
Configure a Custom Key on the event handler to save the entire array
All forms in the collection will be validated simultaneously

Behavior:

Validates all forms across all collection prototype items
Saves the entire modified array in one operation
No additional business rules needed for array synchronization

// Bulk save configuration  
{
  "customKey": "updatedClients",
  "formsToSubmit": ["clientForm"]
}

Bulk save is simpler to implement as it doesn’t require additional business rules to maintain array consistency.

Demo:

Key formation and validation

Understanding how keys work in Forms in Collections is crucial for proper configuration:

Runtime key construction

Keys are automatically constructed using the full object path:

// In your form field configuration
"name"

// What the system generates at runtime
"application.clients[0].name"  // For first item
"application.clients[1].name"  // For second item

Validation behavior

Individual Save Validation

When using Scenario 1 (action inside prototype):

Only validates forms for the specific collection index
Example: If action is triggered on item 2, only clients[1] forms are validated
Other items in the collection are ignored during validation

Bulk Save Validation

When using Scenario 2 (action outside collection):

Validates all forms across all collection items
All items must pass validation for the save to succeed
Comprehensive validation ensures data integrity across the entire collection

Configuration examples

Individual save example

Event handler configuration

{
  "event": "CLICK",
  "actionType": "SAVE_DATA", 
  "nodeActionName": "saveClient",
  "collectionItemSaveKey": "currentClient",
  "formsToSubmit": ["clientDetailsForm"],
  "excludeKeys": ["temporaryData"]
}

Bulk save example

Event handler configuration

{
  "event": "CLICK",
  "actionType": "SAVE_DATA",
  "nodeActionName": "saveAllClients", 
  "customKeys": ["allClients"],
  "formsToSubmit": ["clientDetailsForm"]
}

Troubleshooting

Forms not validating correctly

Symptoms: Validation errors not showing or validation not working as expectedSolutions:

Ensure formsToSubmit includes the correct form identifiers
Check that form fields have proper relative keys configured
Verify the event handler is placed in the correct location (inside or outside prototype)
For individual saves, confirm the Collection Item Save Key is configured

Data not saving properly

Symptoms: Form data not persisting or appearing in wrong locationSolutions:

For individual saves: Ensure business rule updates the original array
For bulk saves: Verify Custom Key configuration captures the full array
Check key formation by examining the process data structure
Confirm the Collection Source points to the correct array

Can't hide form elements based on external variables

Limitation: Form elements within collections cannot be hidden based on variables outside the collectionWorkaround: Use keys from within the collection item object for conditional display. The mechanics of collections require using data from within the current collection item scope.

Frequently asked questions

Can I hide form elements based on variables outside the collection?

No, the mechanics of collections require using keys from within the collection item object. You cannot use variables outside the collection scope to control form element visibility within the collection.

What happens to null values in form fields?

You can configure Exclude Keys in the event handler to handle null values. This prevents null or empty values from being included in the saved data.

How are keys formed at runtime?

Keys are constructed with the full object path including array indices. For example, a field with key name becomes application.clients[0].name for the first collection item.

Do I need business rules for both saving scenarios?

Individual Save (Scenario 1): Yes, you need a business rule to update the original array
Bulk Save (Scenario 2): No, the entire array is saved directly without additional business rules

Best practices

Choose the Right Scenario

Use Individual Save for real-time editing where users work on one item at a time. Use Bulk Save for form-completion workflows where all data is submitted together.

Key Management

Use descriptive, relative keys in your form fields. Let the system handle path construction automatically for better maintainability.

Validation Strategy

Plan your validation approach early. Individual saves validate per item, bulk saves validate everything - choose based on your user experience goals.

Data Structure

Design your array structure to include all necessary fields from the start. Adding fields later may require updates to existing prototypes.

This feature significantly simplifies building dynamic forms with repeatable sections, eliminating the need for custom development while providing flexible validation and saving options.

Common patterns

Display a list of plain values (string or number array)

A Collection binds each child component to a key on the current item, so the source must be an array of objects. You can’t bind a raw array of primitives like ["Red", "Green", "Blue"] directly, because there is no key to point a component at. To display a plain array, wrap each value in an object first, then bind a component to that key.

Transform the array into objects

Add a business rule that maps each primitive into an object with a single key (for example, value):

var colors = input.colors || ["Red", "Green", "Blue"];

var items = colors.map(function (c) {
    return { "value": c };
});

output.put("displayed", { "colors": items });

This produces [{ "value": "Red" }, { "value": "Green" }, { "value": "Blue" }].

Point the Collection at the transformed array

Set the Collection Source to the transformed key (for example, displayed.colors).

Bind a component to the wrapper key

Inside the Collection Prototype, add a Text (or other) component and set its key to the relative key value. At runtime it resolves to displayed.colors[0].value, displayed.colors[1].value, and so on.

You can name the wrapper key anything (value, label, name), just make sure the component’s relative key matches it.

Delete an item from a collection

Collections do not have a built-in delete mechanism. To remove an item, use a business rule triggered from within the collection prototype.

Add a delete button inside the Collection Prototype

Place a button inside your Collection Prototype. Add an event handler with:

Event: CLICK
Action Type: ACTION
Node Action Name: your delete business rule
Collection Item Save Key: a temporary key (e.g., itemToDelete) — this saves the clicked item’s data so the business rule knows which item to remove

Create the delete business rule

Add a manual, optional, repeatable business rule on the User Task node.Delete by matching an attribute (when items have no unique ID):

var clients = input.application.clients || [];
var itemToDelete = input.itemToDelete;

if (itemToDelete != null) {
    for (var i = 0; i < clients.length; i++) {
        if (clients[i].name === itemToDelete.name 
            && clients[i].email === itemToDelete.email) {
            clients.splice(i, 1);
            break;
        }
    }
}

output.application = { "clients": clients };

Delete by ID (when items have a unique identifier):

var clients = input.application.clients || [];
var itemToDelete = input.itemToDelete;

var updated = clients.filter(function(item) {
    return item.id !== itemToDelete.id;
});

output.application = { "clients": updated };

Send the updated array back to the UI

Add a Send Data to User Interface action to push the modified array back:

{
  "application": ${application}
}

Always send the updated array back to the frontend after deletion. Without this step, the UI will still display the deleted item until the next page refresh.

Add an item to a collection dynamically

To let users add new entries to a collection (e.g., an “Add” button), create a business rule that appends a new object to the source array.

var clients = input.application.clients || [];

var newClient = {
    "id": clients.length + 1,
    "name": "",
    "email": ""
};

clients.push(newClient);

output.application = { "clients": clients };

Place the “Add” button outside the collection, and attach an event handler (type ACTION) pointing to this business rule. Then send the data back to the UI with a Send Data to User Interface action.

Filter a collection using form controls

Collections do not have built-in filtering. To filter displayed items based on form selections, use the same pattern as Table cross-component filtering:

Keep the original data in one key (e.g., application.clients)
Store the displayed data in a separate key (e.g., displayed.clients)
Point the Collection’s Source to the displayed key
On each filter dropdown’s CHANGE event, trigger a business rule that filters the original data and writes the result to the displayed key

var allClients = input.application.clients || [];
var selectedStatus = input.filter.status;

var filtered = allClients.filter(function(item) {
    if (selectedStatus && item.status !== selectedStatus) return false;
    return true;
});

output.displayed = { "clients": filtered };

For simple client-side transformations (no server roundtrip needed), you can also use Event Handlers with an onChange expression instead of a business rule.

Academy courses

Collections and Prototypes course

Hands-on course covering collection configuration, service tasks, and business rules with collections

Handle Dynamic Data course

Learn to configure dynamic dropdowns and data-driven UI from process data

Academy playground — explore the Academy_DynamicDataHandling project for working examples of dynamic data in collections and dropdowns.

Getting Started

Concepts

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

Resources

API reference

Configurable properties

Example usage

Collection prototype

Forms in collections

Overview

How it works

Implementation guide

Saving scenarios

Business rule Examples

Key formation and validation

Runtime key construction

Validation behavior

Configuration examples

Individual save example

Bulk save example

Troubleshooting

Frequently asked questions

Best practices

Choose the Right Scenario

Key Management

Validation Strategy

Data Structure

Common patterns

Display a list of plain values (string or number array)

Delete an item from a collection

Add an item to a collection dynamically

Filter a collection using form controls

Academy courses

Collections and Prototypes course

Handle Dynamic Data course

​Configurable properties

​Example usage

Collection prototype

​Forms in collections

​Overview

​How it works

​Implementation guide

​Saving scenarios

​Business rule Examples

​Key formation and validation

​Runtime key construction

​Validation behavior

​Configuration examples

​Individual save example

​Bulk save example

​Troubleshooting

​Frequently asked questions

​Best practices

Choose the Right Scenario

Key Management

Validation Strategy

Data Structure

​Common patterns

​Display a list of plain values (string or number array)

​Delete an item from a collection

​Add an item to a collection dynamically

​Filter a collection using form controls

​Academy courses

Collections and Prototypes course

Handle Dynamic Data course

Configurable properties

Example usage

Forms in collections

Overview

How it works

Implementation guide

Saving scenarios

Business rule Examples

Key formation and validation

Runtime key construction

Validation behavior

Configuration examples

Individual save example

Bulk save example

Troubleshooting

Frequently asked questions

Best practices

Common patterns

Display a list of plain values (string or number array)

Delete an item from a collection

Add an item to a collection dynamically

Filter a collection using form controls

Academy courses