Skip to main content

​
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 powerful 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.
Forms in Collections
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:
  1. Data Structure: Your process data contains an array of objects (e.g., application.clients)
  2. UI Configuration: Collection component points to your array, and Form components are placed inside Collection Prototypes
  3. Key Generation: Form field keys are automatically prefixed with the collection path and item index
  4. Runtime Behavior: Each collection item gets its own form instance with properly scoped keys

​
Implementation guide

1

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 });
2

Create the Collection component

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

Add Collection Prototype with Forms

  1. Add a Collection Prototype as a child of your Collection component
  2. Configure prototype identifier. This is the key that will be used to identify the prototype.
  3. Drag Form components directly into the Collection Prototype
  4. Configure form fields with relative keys (e.g., name, email)
Collection configuration for forms
This is the key innovation: you can now place Form components directly inside Collection Prototypes, and they will automatically repeat for each collection item.
4

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 UI action
  • 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
Collection configuration for forms
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

// 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"
    };
}


{ "application": ${application}}
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"

​
Validation behavior

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

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

​
Bulk save example

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

​
Troubleshooting

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 UI action is placed in the correct location (inside or outside prototype)
  • For individual saves, confirm the Collection Item Save Key is configured
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
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

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.
You can configure Exclude Keys in the UI action to handle null values. This prevents null or empty values from being included in the saved data.
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.
  • 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.