Extracting additional data in business rules

Business rules in FlowX.AI allow you to extract and use key values dynamically. This is essential for handling user security details, configuration parameters, and business logic calculations.

This guide is covering the following:

✅ Retrieving security details dynamically
✅ Extracting specific user attributes
✅ Fetching configuration parameters

Extracting security details

Security details (securityDetails) store user-related data, including email, username, roles, and permissions. These values are stored in additionalData.securityDetails and can be accessed dynamically within business rules and workflow scripts.

The securityDetails structure differs between processes and workflows. Processes group security details by swimlane and role, while workflows use a simplified flat structure. See the tabs below for both formats.

Test mode behaves differently from runtime. additionalData (including securityDetails) is populated by the platform at execution time, so its availability when you use the Test action depends on the context:

• Process business rule Test: additionalData is injected automatically when the rule runs, so securityDetails resolves the same way it does at runtime.
• Workflow script Test: additionalData is not injected automatically. To test a script in isolation, add the securityDetails structure manually to the test input. Without it, the script works during a full workflow run but returns no security details when run through Test alone.

In processes

Retrieve security details

Use the following business rule to fetch and store security details:

// Retrieve security details from additionalData
securityDetails = additionalData.get("securityDetails");

// Store the extracted security details
output.put("securityDetails", securityDetails);

Example output:

{
    "securityDetails": {
        "Default": {
            "owner": {
                "username": "[e-mail]",
                "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600",
                "details": {
                    "firstName": "John",
                    "lastName": "Snow",
                    "email": "[e-mail]",
                    "jwt": "your_jwt",
                    "roles": [],
                    "groups": [
                        "/Users/Flowx_demo",
                        "/superAdmin"
                    ],
                    "attributes": {}
                }
            }
        }
    }
}

In processes, securityDetails is grouped by swimlane name (e.g., Default) and role (e.g., owner). This structure reflects the BPMN swimlane and role assignments configured in the process definition.

Extract specific owner details

To retrieve specific attributes, such as email, username, first name, and last name, use one of the following scripts (JS or Python):

JavaScript

// Retrieve security details
securityDetails = additionalData.get("securityDetails");
// Extract owner details from the Default swimlane
email = securityDetails.Default.owner.details.email;
username = securityDetails.Default.owner.username;
firstName = securityDetails.Default.owner.details.firstName;
lastName = securityDetails.Default.owner.details.lastName;

// Store extracted details in the output
output.put("email", email);
output.put("username", username);
output.put("firstName", firstName);
output.put("lastName", lastName);

Python

# Retrieve security details
security_details = additionalData.get("securityDetails")
# Extract owner details from the Default swimlane
email = security_details["Default"]["owner"]["details"]["email"]
username = security_details["Default"]["owner"]["username"]
first_name = security_details["Default"]["owner"]["details"]["firstName"]
last_name = security_details["Default"]["owner"]["details"]["lastName"]

# Store extracted details in the output
output["email"] = email
output["username"] = username
output["firstName"] = first_name
output["lastName"] = last_name

Extracted values:

• Owner Email (securityDetails.Default.owner.details.email)
• Username (securityDetails.Default.owner.username)
• First Name (securityDetails.Default.owner.details.firstName)
• Last Name (securityDetails.Default.owner.details.lastName)

Dynamic extraction by swimlane

If your application uses multiple swimlanes, retrieve the owner details dynamically:

// Get security details
securityDetails = additionalData.get("securityDetails");

// Extract owner details based on the swimlane
ownerDetails = securityDetails.Default.owner.details;

<Info>
Default is the swimlane name in this example. Replace it with your swimlane name.
</Info>

// Store extracted values in the process instance
output.put("email", ownerDetails.email);
output.put("username", securityDetails.Default.owner.username);
output.put("firstName", ownerDetails.firstName);
output.put("lastName", ownerDetails.lastName);

Example output:

{
  "email": "[e-mail]",
  "username": "[e-mail]",
  "firstName": "John",
  "lastName": "Snow"
}

In workflows

Retrieve security details

In workflow scripts, securityDetails uses a flat structure — there is no swimlane or role grouping, since workflows do not have swimlanes.

// Retrieve all additional data
const additionalParams = additionalData;

// Access security details directly
output.put("securityDetails", additionalParams.securityDetails);

Example output:

{
  "securityDetails": {
    "username": "[e-mail]",
    "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600",
    "details": {
      "firstName": "John",
      "lastName": "Snow",
      "email": "[e-mail]",
      "roles": ["ROLE_ADMIN", "ROLE_USER"],
      "groups": ["/Users/Flowx_demo", "/superAdmin"],
      "attributes": {}
    }
  }
}

Field	Description
username	The authenticated user’s username
identifier	The user’s unique identifier (Keycloak subject ID)
details.firstName	User’s first name
details.lastName	User’s last name
details.email	User’s email address
details.roles	Roles assigned to the user in the authentication token
details.groups	Groups the user belongs to in the authentication token
details.attributes	Additional user attributes from the authentication token (empty object if none are set)

Unlike process securityDetails, workflows do not include the jwt field, and they use a flat structure (no swimlane or role grouping).

Extract specific user details

Since the structure is flat, you can access user attributes directly without navigating swimlane or role levels:

JavaScript

// Retrieve security details
securityDetails = additionalData.securityDetails;

// Extract user details directly (no swimlane grouping)
email = securityDetails.details.email;
username = securityDetails.username;
identifier = securityDetails.identifier;
firstName = securityDetails.details.firstName;
lastName = securityDetails.details.lastName;
roles = securityDetails.details.roles;
groups = securityDetails.details.groups;

// Store extracted details in the output
output.put("email", email);
output.put("username", username);
output.put("identifier", identifier);
output.put("firstName", firstName);
output.put("lastName", lastName);
output.put("roles", roles);
output.put("groups", groups);

Python

# Retrieve security details
security_details = additionalData["securityDetails"]

# Extract user details directly (no swimlane grouping)
email = security_details["details"]["email"]
username = security_details["username"]
identifier = security_details["identifier"]
first_name = security_details["details"]["firstName"]
last_name = security_details["details"]["lastName"]
roles = security_details["details"]["roles"]
groups = security_details["details"]["groups"]

# Store extracted details in the output
output["email"] = email
output["username"] = username
output["identifier"] = identifier
output["firstName"] = first_name
output["lastName"] = last_name
output["roles"] = roles
output["groups"] = groups

Extracted values:

• Email (securityDetails.details.email)
• Username (securityDetails.username)
• Identifier (securityDetails.identifier)
• First Name (securityDetails.details.firstName)
• Last Name (securityDetails.details.lastName)
• Roles (securityDetails.details.roles)
• Groups (securityDetails.details.groups)

Structure comparison

Field	Process path	Workflow path
Email	securityDetails.Default.owner.details.email	securityDetails.details.email
Username	securityDetails.Default.owner.username	securityDetails.username
Identifier	securityDetails.Default.owner.identifier	securityDetails.identifier
First Name	securityDetails.Default.owner.details.firstName	securityDetails.details.firstName
Last Name	securityDetails.Default.owner.details.lastName	securityDetails.details.lastName
Roles	securityDetails.Default.owner.details.roles	securityDetails.details.roles
Groups	securityDetails.Default.owner.details.groups	securityDetails.details.groups
Attributes	securityDetails.Default.owner.details.attributes	securityDetails.details.attributes
JWT	securityDetails.Default.owner.details.jwt	Not available

If you are migrating business rule logic from a process to a workflow, update the securityDetails access paths. The swimlane (e.g., Default) and role (e.g., owner) levels do not exist in the workflow structure.

---

Extracting values from configuration parameters

To make business rules flexible, store configuration values in project configuration parameters instead of hardcoding them.

Retrieve configuration parameters

Use a business rule to fetch and store configuration parameter values dynamically:

// Retrieve a configuration parameter (e.g., commission percentage)
commissionPercentage = additionalData.applicationConfiguration.get("commissionPercentage");

// Store the retrieved value in output in the process instance
output.put("commissionPercentage", commissionPercentage);

Example use case: commission calculation

This example shows how to calculate a commission value dynamically using a configuration parameter.

Configuration parameters

Parameter Name	Description	Example Value
commissionPercentage	The percentage used to calculate the commission	0.05 (5%)

Configuration parameters can be modified in:

➡ FlowX.AI Designer → Your Project → Configuration Parameters

Process flow

1. User Inputs an Amount

   In a User task we have an input UI element where the user provides an amount (userInputAmount).

   
2. Retrieve Commission Percentage from Configuration

   In the next node, a Service Task fetches the commissionPercentage from the configuration parameters.

   

   Business rule used:

   // Retrieve user input
   amount = input.get("userInputAmount");
   
   // Retrieve a value from configuration
   commissionPercentage = additionalData.applicationConfiguration.get("commissionPercentage");
   
   // Apply the configuration value
   commissionValue = amount * commissionPercentage;
   
   // Store the calculated result in the process instance
   output.put("commissionValue", commissionValue);
   
   
3. Calculate Commission

   Formula used to calculate the commission:

   $$\text{commissionValue} = \text{userInputAmount} \times \text{commissionPercentage}$$
4. Store and Output the Result

   The computed commissionValue is stored for further processing.

   Final result:

   

Why Use Configuration Parameters?

✅ Keep business rules flexible by avoiding hardcoded values.
✅ Adapt calculations dynamically based on environment settings.
✅ Simplify updates by modifying values in the project configuration rather than editing business rules.