Update process variables

Available starting with FlowX.AI 5.3.0: Update Process Variables allows operations teams to modify process variables on active instances to resolve production issues without developer intervention.

Overview

Update Process Variables allows you to modify process variables on active process instances. You can edit, add, or delete variables on process instances with Started or On Hold status.

This feature is part of operational process instance management, allowing teams to resolve data issues without developer intervention.

The editor provides:

JSON syntax validation and formatting
Edit, add, or delete operations on variables
Automatic synchronization to Task Manager and Elasticsearch
Audit logging with snapshots of previous values

Features

JSON editor

The JSON editor offers:

JSON syntax validation
Syntax highlighting
Auto-formatting
Error detection

Edit process variables using the JSON editor with JSON validation

Access points

Access the editor from two locations:

From Process Instances page
From View process instance page

Navigate to Processes → Active Process → Process instances
Click the contextual menu (three dots) on any process instance row
Select Modify Variables
The system navigates to the Process Instance page and opens the Variables tab in edit mode

Edit process variables using the JSON editor with JSON validation

Dual view modes

Switch between two viewing modes for process variables:

Tree View (existing): Hierarchical display of variables with expand/collapse

Tree view of process variables

JSON View: Raw JSON format, editable when in edit mode

JSON view of process variables

The Export button is available near the view dropdown for downloading process variables.

Operations

You can:

Edit existing attribute values
Add new attributes or objects
Delete existing attributes or objects

All operations are performed in the JSON editor with validation before saving.

Access requirements

Check permissions

Ensure you have the process_variables_edit permission at the workspace level.

The Edit option is only visible to users with this permission.

Navigate to process instance

Access from either:

Process Instances list → contextual menu
Process Instance detail page → secondary navigation

Open Variables tab

Click Edit Variables from the contextual menu. The Variables tab opens in edit mode.

Editing process variables

Select active instance

Choose an active process instance with Started or On Hold status.

Only process instances in Started or On Hold status can have their variables modified.

Switch to JSON View

In the Variables tab, switch from Tree View to JSON View using the view dropdown selector.

Enable edit mode

Click the Edit button to make the JSON editor editable.

This button is only visible if you have the process_variables_edit permission.

Modify variables

Edit process variables in the JSON editor:Example - Editing existing values:

{
  "application": {
    "customer": {
      "id": "12345",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "status": "approved"
  }
}

Example - Adding new attributes:

{
  "application": {
    "customer": {
      "id": "12345",
      "name": "John Doe",
      "email": "[email protected]",
      "phoneNumber": "+1234567890"
    },
    "status": "approved",
    "creditScore": 750
  }
}

Example - Deleting attributes:Remove unwanted attributes by deleting their lines from the JSON.

Validate JSON

Ensure your JSON format is valid before saving.

You cannot save if the JSON format is invalid. The JSON editor will highlight syntax errors automatically.

Common validation errors:

Missing commas between properties
Unclosed brackets or braces
Missing quotes around strings
Trailing commas

Save changes

Click Save to apply your changes.The system automatically:

Creates a snapshot of previous values in a new table
Updates the process instance variables
Syncs to Task Manager (using existing mechanisms)
Updates Elasticsearch (for variables configured for data search)
Records the modification in the audit log

Review audit log

Navigate to the Audit Log tab to confirm the modification was recorded with all details.

Permissions and security

Access control: This feature requires the workspace-level permission wks_process_instance_variables_edit (permission name: process_variables_edit). Users with this permission can edit and save variables; others can only view variables in read-only mode. By default, ORG_ADMIN and WORKSPACE_ADMIN roles include this permission.Security features: All modifications are logged in the audit trail with user identity and timestamp. Previous values are preserved in snapshot history before changes are applied. JSON syntax validation prevents data corruption.For more information about permissions, roles, and access management, see Workspaces Access Rights and the Permission Reference Guide.

Data synchronization

Updated automatically

When you modify process variables, the following are updated:

Process instance parameters

Variables are updated immediately in the database

Task Manager

Variables sync using existing mechanisms; task keywords and data remain consistent

Elasticsearch

Variables configured for data search are updated automatically

Snapshot table

Previous values are saved in a snapshot table before changes are applied

Not updated

The following are preserved to maintain data integrity:

Process snapshots

Snapshots used for back navigation (Reset process data) remain unchanged

Debug records

Process instance debug records preserve execution history as it occurred

Existing audit logs

Previously recorded audit logs (manual actions, integrations) are not modified

Subprocess variables

Child subprocess variables are not updated; parent changes don’t cascade to children

Synchronization details

Task manager sync

Show How it works

Uses existing Task Manager synchronization mechanisms
Updates task keywords if variables are configured as keywords
Maintains task searchability and filtering

Show What gets synced

Task data fields mapped to process variables
Search keywords derived from variables
Custom task metadata

Show Timing

Synchronization happens immediately after save
Typically completes within seconds
No manual intervention required

Elasticsearch sync

Show How it works

Automatically updates Elasticsearch indexes
Only affects variables configured for data search
Uses existing indexing mechanisms

Show What gets synced

Variables marked for Elasticsearch indexing
Data search fields
Process instance searchable data

Show Timing

Index update happens immediately
Index refresh typically within seconds
Search availability may have slight delay

Audit logging

Audit log structure

Every process variable modification creates a detailed audit log entry with the following information:

Field	Description	Example
Workspace	Workspace ID where modification occurred	`ws-12345`
Feature	Feature being used	`Process variables`
Section	Section within the feature	`Process Instance`
App ID	Application UUID	`app-uuid-123`
Application Name	Name of the app	`Loan Application`
Subject	What was modified	`Process variables`
Event	Type of event	`Edit`
Subject Identifier	Process instance UUID	`pi-uuid-456`
Body	JSON with new process parameters	Complete JSON object
User	User who made the change	`[email protected]`
Timestamp	When the change occurred	`2025-01-15T10:30:00Z`

Viewing audit logs

Audit logs are displayed in the Audit Log tab within the process instance:

Open process instance

Navigate to the process instance that was modified.

Go to Audit Log tab

Click the Audit Log tab to view all events for this instance.

Find modification entry

Look for entries with Event = “Edit” and Subject = “Process variables”.

Review details

Click on the audit log entry to see:

Complete before/after values (in Body field)
User who made the change
Exact timestamp
All metadata

Compliance and traceability

Who

User identity

What

Complete JSON body

When

Timestamp

Where

Workspace, app, instance

Previous values

Snapshot history

Important considerations

Subprocess impact

Limitation: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.

Show Why this happens

Each subprocess receives a copy of variables at start time
Subprocesses execute independently with their own variable context
Modifying parent variables doesn’t trigger subprocess updates

Show Impact

Parent and child processes may have inconsistent data
Subprocess logic executes based on original values
Manual coordination needed if subprocess data must match

Show Recommendation

Understand parent-child relationships before modifying variables
Consider if subprocess data consistency is critical
Document any intentional data divergence
Test subprocess behavior after parent modifications

Limitation: Process snapshots used for “Allow back to this action” with “Reset process data” are not updated. Users navigating back will see original values, not modified ones.

Show Why this happens

Snapshots preserve process state at specific points in time
Back navigation restores from these historical snapshots
Modified variables exist only in the current state

Show Impact

Back navigation reverts to pre-modification values
User changes after modification may conflict
Process flow may not reflect recent modifications

Show Recommendation

Use cautiously on processes with back navigation enabled
Warn users if back navigation is available
Consider disabling back navigation for affected nodes
Document this behavior for operations team

Integration messages

Limitation: If a token is waiting for an integration message, the integration was called with original values. Modifying variables after integration calls does not re-trigger integrations.

Show Why this happens

Integrations are called with specific parameters
External systems process requests independently
Responses are based on original request data

Show Impact

Integration responses won’t reflect modified variables
Modified variables won’t affect pending integration results
Data mismatch possible between integration and process

Show Recommendation

Avoid modifying variables while waiting for integration responses
Consider re-executing nodes if integration data needs updating
Understand which variables were sent to integrations
Test integration scenarios carefully

Process instance debug table

Not updated: the process instance debug table records remain unchanged. Reason: debug records capture execution history as it occurred. Modifying them would compromise debugging and troubleshooting capabilities.

Best practices

When to use

Correct user input errors

Fix incorrect data submitted in forms

Unblock stuck instances

Resolve missing data preventing continuation

Fix integration data issues

Correct incorrect responses from external systems

Add missing attributes

Add required data not collected initially

Remove invalid data

Clean up test or incorrect data

Update search keywords

Correct Task Manager search data

Fix Elasticsearch data

Ensure accurate search results

When not to use

Regular operational updates

Design proper process flows instead

Subprocess coordination

Parent-child sync not supported

Complex back navigation flows

Snapshots won’t reflect changes

While waiting for integrations

Responses based on original values

Routine data corrections

Indicates process design issues

Automated scripts

Use process design and actions instead

Validation before saving

Verify JSON syntax

Ensure valid JSON format to prevent data corruption and save failures

Review impact

Understand which variables you’re changing and their impact on process flow

Check dependencies

Review process flow, subprocesses, and integrations before modifying critical variables

Document changes

Audit logs record changes automatically, but document why changes were made

Testing and validation

Test in lower environments first

When possible, test variable modifications in staging or UAT before production.

Verify Elasticsearch sync

If variables are used in data search, confirm updates synced successfully by performing a search.

Check Task Manager

Verify task keywords updated if variables affect task search or filtering.

Monitor process flow

Watch the process after modification to ensure it continues executing as expected.

Review audit log

Confirm the modification was logged correctly with all expected details.

Operational guidelines

Before modifying
During modification
After modification

Review process state

Check current process state and token position

Check subprocesses

Verify if there are running subprocesses

Verify integrations

Ensure no pending integration responses

Understand navigation

Review back navigation points

Document reason

Record why modification is needed

Common use cases

1. Correct user input errors

Scenario:
Customer submitted incorrect loan data (wrong income amount, invalid address, incorrect contact information). Solution:

Navigate to the process instance
Access Variables tab in edit mode
Locate the incorrect values in JSON

Correct the data:

{
  "application": {
    "income": 75000,  // Changed from 50000
    "address": "123 Main St, New York, NY 10001"  // Corrected
  }
}

Save changes
Process continues without requiring customer to restart the process

2. Unblock stuck process instances

Scenario:
Process is waiting for external data that never arrives due to integration timeout or external system being down indefinitely. Solution:

Identify the variable causing the blockage
Open process variables in edit mode

Update the variable to provide expected data or bypass condition:

{
  "integration": {
    "responseReceived": true,  // Manually set to true
    "creditCheckStatus": "completed"  // Provide expected value
  }
}

Save changes
Instance unblocks and continues execution

3. Fix integration data issues

Scenario:
External credit check system returned incorrect or incomplete data due to system error. Solution:

Review the integration response variables

Edit variables to correct the data:

{
  "creditCheck": {
    "score": 720,  // Corrected from incorrect 520
    "status": "approved",  // Fixed status
    "provider": "ExternalCreditBureau"
  }
}

Save changes
Process continues with accurate data

4. Add missing attributes

Scenario:
Process needs additional data that wasn’t collected at start time, but is now required for a decision point. Solution:

Access process variables

Add new required attributes:

{
  "application": {
    "existingField": "value",
    "newlyRequiredField": "new value",  // Added
    "additionalData": {  // Added entire object
      "field1": "value1",
      "field2": "value2"
    }
  }
}

Save changes
Process can now access the missing data at decision points

5. Delete invalid data

Scenario:
Process contains test data or incorrect objects that shouldn’t be there and are causing validation failures. Solution:

Open process variables

Remove problematic data:

{
  "application": {
    "validData": "correct value"
    // Removed "testData": {...}
    // Removed "invalidObject": {...}
  }
}

Save changes
Process continues with clean, valid data only

6. Update task manager keywords

Scenario:
Task search keywords need updating based on corrected customer data for better task discoverability. Solution:

Modify variables that are configured as Task Manager keywords:

{
  "customer": {
    "name": "Jane Smith",  // Corrected
    "accountNumber": "ACC-98765",  // Updated
    "status": "active"
  }
}

Save changes
System automatically syncs to Task Manager
Tasks become searchable with correct keywords

7. Fix Elasticsearch search data

Scenario:
Process data indexed for search contains errors, making instances unsearchable or showing in wrong search results. Solution:

Identify variables configured for Elasticsearch data search

Correct the values:

{
  "searchableData": {
    "category": "loans",  // Corrected from "loans_test"
    "priority": "high",  // Fixed
    "customerSegment": "premium"  // Updated
  }
}

Save changes
Elasticsearch automatically updates
Process instances appear in correct search results

8. Emergency business rule changes

Scenario:
Regulatory change requires immediate update to pricing or terms in active applications. Solution:

Access affected process instances

Update variables to reflect new business rules:

{
  "pricing": {
    "interestRate": 3.5,  // Updated per regulation
    "fees": {
      "processing": 50,  // Adjusted
      "regulatory": 25   // New fee added
    }
  }
}

Save changes for all affected instances
Processes continue with compliant data

Troubleshooting

Edit button not visible

Symptoms:

Cannot see Edit option in contextual menu
Variables tab shows read-only view only

Possible causes:

User doesn’t have process_variables_edit permission
Process instance is not active (not Started or On Hold)
Wrong tab selected

Solutions:

Verify user has process_variables_edit permission:
- Check workspace permissions
- Confirm user role includes this permission
- Contact workspace administrator if needed
Check process instance status:
- Only Started or On Hold instances can be edited
- Finished, Failed, or Terminated instances cannot be modified
- Verify status in process instance details
Ensure you’re in Variables tab:
- Switch to Variables tab if in another tab
- Refresh the page if needed

Cannot save - JSON validation error

Symptoms:

Save button disabled or shows error
Red error indicators in editor
Error message: “Invalid JSON format”

Common JSON errors:Missing comma:

{
  "field1": "value1"  // ❌ Missing comma here
  "field2": "value2"
}

Correct:

{
  "field1": "value1",  // ✅ Comma added
  "field2": "value2"
}

Trailing comma:

{
  "field1": "value1",
  "field2": "value2",  // ❌ Trailing comma
}

Unclosed brackets:

{
  "object": {
    "field": "value"
  // ❌ Missing closing }
}

Solutions:

Use JSON editor error highlights to locate issues
Copy JSON to external validator (jsonlint.com)
Check for common issues: commas, brackets, quotes
Validate structure matches JSON specification
Remove trailing commas
Ensure all brackets and braces are closed

Changes not reflected in Task Manager

Symptoms:

Task Manager still shows old values
Task search doesn’t find with new keywords
Task data appears outdated

Possible causes:

Task Manager sync delay
Variables not configured for Task Manager keywords
Task Manager service issues
Cache issues

Solutions:

Wait and refresh:
- Wait 10-30 seconds for sync
- Refresh Task Manager view
- Clear browser cache if needed
Verify configuration:
- Check if variables are configured as task keywords
- Review Task Manager configuration
- Confirm variable mapping is correct
Check system health:
- Verify Task Manager service is running
- Review sync logs for errors
- Check Kafka messages if available
Verify save completed:
- Check audit log for successful save
- Confirm no error messages appeared
- Review process instance variables show new values

Elasticsearch search not showing updated data

Symptoms:

Search doesn’t return expected results
Old values appear in search results
Process instance not found with new criteria

Possible causes:

Elasticsearch sync delay
Variables not configured for data search
Index refresh delay
Elasticsearch service issues

Solutions:

Wait for index refresh:
- Elasticsearch typically refreshes within seconds
- Wait up to 1 minute for propagation
- Try search again after waiting
Verify configuration:
- Check if variables are configured for Elasticsearch indexing
- Review process definition for data search settings
- Confirm variable paths match index mapping
Check Elasticsearch health:
- Verify Elasticsearch service is running
- Check index status
- Review indexing logs for errors
Manual verification:
- Query Elasticsearch directly if possible
- Check index document for process instance
- Verify field values match expected data

Modified variables lost after back navigation

Symptoms:

User navigates back in process
Variables revert to original values
Recent modifications disappeared

This is expected behavior - not a bug.Explanation: Process snapshots used for back navigation are not updated when you modify variables. When users navigate backwards, the process state is restored from the snapshot, reverting to original values.Why this happens:

Snapshots preserve historical process state
Back navigation restores exact point-in-time state
Maintains integrity of back navigation feature

Recommendations:

Document this behavior:
- Inform operations team about snapshot behavior
- Add notes to operational procedures
- Train users on implications
Prevent back navigation:
- Disable back navigation for nodes after modification
- Configure “Allow back to this action” appropriately
- Consider process design implications
Alternative approaches:
- Modify variables only when back navigation unlikely
- Re-apply modifications after back navigation if needed
- Design processes to minimize back navigation needs
User warnings:
- Display warnings before allowing back navigation
- Inform users modifications may be lost
- Provide clear guidance on expected behavior

Subprocess shows different data than parent

Symptoms:

Parent process variables updated
Subprocess still has old values
Data inconsistency between parent and child

This is expected behavior - not a bug.Explanation: Subprocesses receive a copy of variables at start time and execute independently. Modifying parent variables doesn’t cascade to existing child subprocesses.Why this happens:

Subprocesses have independent execution context
Each subprocess operates on its snapshot of data
Maintains process isolation and integrity

Solutions:

Understand before modifying:
- Check if process has active subprocesses
- Review parent-child data dependencies
- Assess impact of data divergence
Manual coordination:
- Modify subprocess variables separately if needed
- Document intentional data divergence
- Test subprocess behavior with original values
Process design considerations:
- Design processes to minimize parent-child data coupling
- Pass critical data as subprocess parameters
- Use events for dynamic data synchronization

Integration response doesn't match modified data

Symptoms:

Integration called before modification
Response based on original values
Data mismatch between variables and integration result

This is expected behavior - not a bug.Explanation: Integrations are called with specific parameters. External systems process requests independently. Modifying variables after the call doesn’t re-trigger the integration or affect the response.Why this happens:

Integration already executed with original parameters
External system processed original request
Response is based on what was sent
Modifying variables is local to process instance

Solutions:

Avoid modifying during integration:
- Check if token is waiting for integration response
- Wait for integration to complete before modifying
- Document which variables were sent to integration
Re-execute if needed:
- Consider re-executing the integration node
- Manually trigger integration with new values if possible
- Design retry mechanisms in process flow
Accept response:
- Use integration response as-is
- Modify only non-integration-related variables
- Document why integration response doesn’t match

Process Instance Overview

Learn about process instances and execution

Process Status

Monitor process execution and troubleshoot issues

Audit Logs

Understand audit logging and compliance tracking

Task Management

Learn about Task Manager integration

Getting Started

Platform overview

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

API reference

​Overview

​Features

​JSON editor

​Access points

​Dual view modes

​Operations

​Access requirements

​Editing process variables

​Permissions and security

​Data synchronization

​Updated automatically

Process instance parameters

Task Manager

Elasticsearch

Snapshot table

​Not updated

Process snapshots

Debug records

Existing audit logs

Subprocess variables

​Synchronization details

​Task manager sync

​Elasticsearch sync

​Audit logging

​Audit log structure

​Viewing audit logs

​Compliance and traceability

Who

What

When

Where

Previous values

​Important considerations

​Subprocess impact

​Back navigation

​Integration messages

​Process instance debug table

​Best practices

​When to use

Correct user input errors

Unblock stuck instances

Fix integration data issues

Add missing attributes

Remove invalid data

Update search keywords

Fix Elasticsearch data

​When not to use

Regular operational updates

Subprocess coordination

Complex back navigation flows

While waiting for integrations

Routine data corrections

Automated scripts

​Validation before saving

Verify JSON syntax

Review impact

Check dependencies

Document changes

​Testing and validation

​Operational guidelines

Review process state

Check subprocesses

Verify integrations

Understand navigation

Document reason

​Common use cases

​1. Correct user input errors

​2. Unblock stuck process instances

​3. Fix integration data issues

​4. Add missing attributes

​5. Delete invalid data

​6. Update task manager keywords

​7. Fix Elasticsearch search data

Overview

Features

JSON editor

Access points

Dual view modes

Operations

Access requirements

Editing process variables

Permissions and security

Data synchronization

Updated automatically

Not updated

Synchronization details

Task manager sync

Elasticsearch sync

Audit logging

Audit log structure

Viewing audit logs

Compliance and traceability

Important considerations

Subprocess impact

Back navigation

Integration messages

Process instance debug table

Best practices

When to use

When not to use

Validation before saving

Testing and validation

Operational guidelines

Common use cases

1. Correct user input errors

2. Unblock stuck process instances

3. Fix integration data issues

4. Add missing attributes

5. Delete invalid data

6. Update task manager keywords

7. Fix Elasticsearch search data

8. Emergency business rule changes

Troubleshooting

Related resources