Finding identifiers and parameters

When integrating with FlowX APIs, configuring Kafka producers, or connecting external systems, you’ll need various identifiers and parameters. This guide shows you exactly where to find each one in the FlowX Designer interface.

Quick tip: Most UUIDs and identifiers in FlowX Designer can be copied by clicking the copy icon next to them or by right-clicking and selecting “Copy UUID” from the context menu.

Common identifiers overview

Workspace ID

Required for multi-tenant environments and data isolation

Application ID

Identifies your project/application in API calls

Build ID

References a specific deployed version of your application

Process IDs

Various identifiers for processes and their instances

Workspace identifiers

Workspace ID (Fx-WorkspaceId)

The workspace ID is used to identify the workspace context in multi-tenant environments. It’s required in certain Kafka headers and API calls.

Access Organization Settings

Navigate to Organization Settings from the main menu (available for organization admins and workspace admins).

Select Workspaces

Click on Workspaces in the left sidebar.

View Workspace List

You’ll see all workspaces listed. Each workspace card displays:

Workspace name
Workspace UUID (this is your Workspace ID)

Copy the UUID

Click the contextual menu (three dots) and then select “Copy UUID” to copy the workspace UUID or copy it directly from the workspace URL when you’re inside a workspace:

https://your-domain.flowx.ai/workspace/{workspace-id}/projects

The workspace ID is also visible in your browser’s address bar when navigating within a workspace.

Default Workspace: If you migrated from a pre-5.x version, your default workspace has the UUID: 00000000-0000-0000-0000-000000000001

Where it’s used:

Kafka header: Fx-WorkspaceId
API calls requiring workspace context
Cross-workspace queries and data isolation

Project identifiers

Project ID (Fx-AppId, appId)

The project ID (also called application ID or app ID) identifies your project within FlowX. It’s one of the most commonly required identifiers.

Navigate to Projects

Go to your workspace and click on Projects in the main navigation.

Select Your Project

Click on the project you’re working with to open it.

Copy from URL or Project Details

The project ID can be found in multiple places:Option 1: From the URL

https://your-domain.flowx.ai/workspace/{workspace-id}/projects/{project-id}/...

Option 2: From Project Settings

Click the three dots to access the contextual menu
Select “Copy UUID” to copy the project UUID

Where it’s used:

Kafka header: Fx-AppId
API path parameter: /app/{appId}/...
Process start requests
Runtime API calls

Root Application ID (Fx-RootAppId)

The root application ID tracks the originating application throughout process chains, especially when processes spawn subprocesses across different components.

In most cases, Fx-RootAppId will be the same as Fx-AppId unless you’re dealing with complex multi-application workflows.

Where it’s used:

Kafka header: Fx-RootAppId
Tracking process chains across multiple applications
Subprocess communication

Build identifiers

Build ID (buildId)

The build ID is a unique identifier for a specific committed version of your application that’s been deployed to runtime.

Navigate to Runtime Builds

From your project, go to Runtime → Builds.

View Build List

You’ll see all your builds listed with:

Build version number
Commit status
Creation date

UI Limitation: Currently, the build UUID is not displayed in the builds list, and there’s no copy UUID button available. You can obtain the build ID through the API or from browser developer tools when viewing build details.

Identify Active Build

Active Policy: The build marked as “Active Policy” is the one currently running in production. This is typically the build you’ll want to use for API calls.

Where it’s used:

API path parameter: /build/{buildId}/...
Runtime endpoints used by renderers
Version-specific API calls

Obtaining Build ID via API

You can retrieve the build ID by calling the builds API endpoint:

GET /appmanager/api/app/{appId}/builds

The response includes all builds with their buildId values.

Application Version ID (appVersionId, Fx-Build-App-Version-Id)

The application version ID (also called appVersionId or applicationVersionId) identifies a specific app version. Unlike buildId, this identifier is not unique by itself - it’s only unique when combined with workspaceId.

Key distinction:

buildId: Unique identifier for a committed build (globally unique)
appVersionId: Identifier for an app version (unique only within a workspace when combined with workspaceId)
Kafka header Fx-Build-App-Version-Id contains the appVersionId, NOT the buildId

Where it’s used:

API path parameter: /app-version/{appVersionId}/...
Kafka header: Fx-Build-App-Version-Id (replaces deprecated Fx-BuildId)
Internal Kafka communication between FlowX components
Always used in combination with workspaceId for unique identification

Technical note: In API responses (e.g., /api/app/{appId}/app-version/{appVersionId}), you may see the app version ID duplicated in both the main response and within a settings.applicationVersionId field. This happens because the settings object represents a separate database table, and the view combines multiple tables without explicitly excluding the duplicate data.

Deprecated Header: Fx-BuildId is deprecated since FlowX 5.0. Use Fx-Build-App-Version-Id instead. Note that this header contains the appVersionId, despite the “Build” in the header name.

Process identifiers

Process Definition Name (processDefinitionName)

The process definition name is the human-readable name you assigned when creating the process.

Navigate to Processes

From your project, go to Definitions → Processes.

View Process List

The process name is displayed prominently for each process in the list.

Copy Process Name

You can copy the exact process name by:

Selecting and copying the text directly
Opening the process and copying from the process settings

Process names are case-sensitive and must match exactly when used in API calls or Kafka messages.

Where it’s used:

API path parameter: /process-name/{processDefinitionName}/start
Kafka header: Fx-ProcessName (when starting a process via Kafka)
Process configuration and queries

Process Definition UUID

Process definitions have two types of UUIDs, each serving different purposes:

Resource Definition ID (resourceDefinitionId, processDefinitionFlowxUuid) - Permanent identifier
Resource ID (resourceId) - Version-specific identifier

Critical distinction:

resourceDefinitionId (also known as processDefinitionFlowxUuid): Stays constant across ALL app versions. This is the logical identifier for the process.
resourceId: Changes with each app version when the process is modified. This identifies a specific version of the process.

Finding Process Definition UUID (resourceDefinitionId)

The resourceDefinitionId is the permanent identifier that stays the same across all versions. This is what you typically need for process references and integrations.

Open the Process

Navigate to Definitions → Processes and click on your process to open it.

Access Process Settings

Click the Settings icon (gear icon) in the process editor toolbar.

Copy UUID

The process UUID displayed in process settings is the resourceDefinitionId.

UI Limitation: Currently, there’s no copy UUID button in the process list view. You need to open the process settings to access the UUID.

Alternatively, you can find it in the browser URL when editing a process:

https://your-domain.flowx.ai/.../processes/{process-uuid}/edit

Where it’s used:

Also referred to as processDefinitionFlowxUuid in some contexts
Process references and linking
Cross-version queries
Most integration scenarios (unless you specifically need a version-specific identifier)

Finding Resource ID (version-specific)

The resourceId identifies a specific version of a process and changes with each app version.

When you might need resourceId: Typically, you won’t need the version-specific resourceId unless you’re working with internal APIs that specifically require it. Most integrations use resourceDefinitionId instead.

Where it’s used:

Version-specific API operations
Internal queries that need to target a specific app version
API responses (returned alongside resourceDefinitionId)

Resource Definition ID (resourceDefinitionId)

The resource definition ID is a persistent identifier for a resource that stays the same across all app versions. It’s used to track the evolution of a resource through different versions and to link resources together.

Key difference from resourceId:

resourceDefinitionId: Permanent identifier that stays constant across versions. Use this to link resources together (e.g., a process using another process, a process using a workflow) and to track changes between different versions of the same resource.
resourceId: Version-specific identifier that changes with each app version. Use this when you need to modify or reference a specific version of a resource.

How to find it: This ID is not directly visible in the FlowX Designer UI. It’s returned in the response body when you make a GET request to fetch a specific resource by its resource ID.

Via API Response
Via List Endpoints
Via Browser DevTools

The resourceDefinitionId is present in every resource request (GET, update, delete). The URL pattern follows:

/appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/{resourceType}/ri/{resourceId}/...

Examples by resource type:Workflows:

GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/workflow/ri/{resourceId}/integration/api/workflows/getById

Processes:

GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/process/ri/{resourceId}/...

The response includes the resourceDefinitionId:

{
  "resourceId": "36ab1a35-fc4e-49ee-872d-b3551e3e33ce",
  "resourceDefinitionId": "e96fb0fb-a710-44db-b3bd-1a57bc2cb3e8",
  "applicationId": "fd44d9d9-b072-40fe-b12e-b7714105ba48",
  "name": "My Resource",
  ...
}

Where it’s used:

Linking resources: When one resource references another (process calls another process, process uses a workflow, etc.)
Version tracking: To track how a resource evolves across different app versions
Cross-version queries: Finding all versions of the same logical resource
API responses: Present in both individual resource requests and list endpoints

When to use resourceDefinitionId vs resourceId:

Use resourceDefinitionId when you need to reference a resource logically, regardless of version
Use resourceId when you need to work with a specific version of a resource (editing, viewing, deploying)

Understanding the relationship: A practical example

Example: Process referencing a Workflow across versions

Let’s say you have:

Process A (Customer Onboarding)
Workflow B (Document Verification)

Scenario: Process A needs to use Workflow B.Version 1.0 (Initial):

{
  "workflowB": {
    "resourceId": "abc-123-v1",
    "resourceDefinitionId": "workflow-doc-verify"
  }
}

Process A references Workflow B using resourceDefinitionId: "workflow-doc-verify"Version 2.0 (After modifying Workflow B):

{
  "workflowB": {
    "resourceId": "abc-456-v2",          // ⬅️ Changed
    "resourceDefinitionId": "workflow-doc-verify"  // ⬅️ Stays the same
  }
}

✅ The link still works because Process A uses resourceDefinitionId, which remains constant.Why this matters:

When you modify Workflow B and create a new app version, its resourceId changes from abc-123-v1 to abc-456-v2
But resourceDefinitionId stays workflow-doc-verify
Process A doesn’t need to be updated because it references the logical resource, not a specific version
FlowX automatically resolves to the latest version of Workflow B in the active build

When modifying resources:

Use resourceId in your API calls to edit/update/delete a specific version
Use resourceDefinitionId to understand which logical resource is being modified
Use resourceDefinitionId to track history: “Show me all versions of this workflow”

Process Instance UUID (processInstanceUuid)

When you start a process, FlowX creates a process instance with its own unique identifier.

Access Active Processes

Navigate to Runtime → Active Process → Process instances.

View Process Instances

You’ll see a list of all running and completed process instances.

Open Process Status

Click on a process instance to view its details, then click the Process Status icon.

Copy Instance UUID

At the top of the process status view, you’ll see:

Active process instance: The UUID of this specific process execution
Click the copy icon to copy the UUID

Where to find it programmatically: Process instance UUIDs are returned in the response when you start a process via API. Store this value if you need to reference the instance later.

Where it’s used:

Kafka header: processInstanceUuid
API calls to query or manipulate specific process instances
Correlation in Kafka messages
Audit log queries

Process Instance ID (processInstanceId)

In addition to the UUID, each process instance has a numeric ID.

View in Process Status

Open the process status (as described above for Process Instance UUID).

Check Instance Metadata

Scroll to the Instance Metadata section, which displays:

processInstanceId: The numeric ID
processInstanceUuid: The UUID

Both processInstanceId (numeric) and processInstanceUuid (UUID) identify the same process instance. Use the UUID for most integrations as it’s globally unique.

Where it’s used:

Kafka header: processInstanceId
Internal database queries
Some legacy integrations

Token identifiers

Token ID

Tokens represent the current position in a process flow. Each token has an identifier.

Open Process Status

Navigate to Runtime → Active Process → Process instances and open a process instance.

View Tokens Section

In the process status view, expand the Tokens section.

Identify Token

Each token displays:

Token ID (numeric)
Token state (ACTIVE, FINISHED, etc.)
Current node position

Where it’s used:

Advanced process debugging
Custom integrations that need to track token movement
Internal FlowX Engine operations

Context and correlation identifiers

fxContext

The fxContext header is crucial for routing messages in architectures with embedded processes and subprocesses.

fxContext structure:

Root process: "main"
Embedded subprocess (nodeId=4): "main:4"
Sub-subprocess (nodeId=12 inside subprocess 4): "main:4:12"

This value is automatically set by FlowX Engine when sending Kafka messages. You must preserve and return it unchanged in your responses.

Where it’s used:

Kafka header: fxContext
Routing messages to specific subprocesses
Message correlation in complex process hierarchies

Authentication identifiers

JWT Token

Most API calls and Kafka messages require authentication via JWT token.

Obtain from Browser (Development/Testing)

For Development and Testing Only:

Log into FlowX Designer
Open browser developer tools (F12)
Go to the Network tab
Make any request in FlowX Designer
Click on the request and view headers
Find the Authorization header and copy the JWT token (the part after “Bearer ”)

Tokens obtained this way are temporary and tied to your user session. They will expire quickly and should only be used for development and testing purposes.

Production Authentication

For Production Integrations:In production environments, external systems should authenticate using your configured Identity Provider (Keycloak or other OAuth2 provider) with appropriate user credentials or OAuth2 flows based on your security requirements.

Work with your Customer Success team or security administrator to set up proper authentication flows for your production integrations. The authentication method will depend on your specific use case and security policies.

Security considerations:

Never hardcode JWT tokens in your code. Tokens expire and should be refreshed regularly.
Service accounts (client credentials flow) have elevated privileges in FlowX and should be handled with extreme care.
For on-premise deployments: Service account setup should be coordinated with your Customer Success team.
For cloud deployments: Contact FlowX support to discuss proper authentication strategies for your integration needs.

Where it’s used:

HTTP header: Authorization: Bearer {token}
Kafka header: jwt (for process starts via Kafka)
All authenticated API calls

Quick reference table

Here’s a quick lookup table for common identifiers:

Identifier	Also Known As	Format	Where to Find	Used In
Workspace ID	`Fx-WorkspaceId`	UUID	Organization Settings → Workspaces OR URL	Kafka headers, API calls
Application ID	`appId`, `Fx-AppId`	UUID	Project URL, Project Settings	API paths, Kafka headers
Root Application ID	`Fx-RootAppId`	UUID	Same as Application ID (in most cases)	Kafka headers
Build ID	`buildId`	UUID	API: `/api/app/{appId}/builds`	Runtime API paths
Application Version ID	`appVersionId`, `applicationVersionId`, `Fx-Build-App-Version-Id`	UUID	Runtime → Builds (not directly visible in UI)	API paths, Kafka headers
Process Definition Name	`processDefinitionName`	String	Definitions → Processes (process name)	API paths, Kafka headers
Process Definition UUID	`processDefinitionFlowxUuid`, `resourceDefinitionId`	UUID	Process Settings OR URL when editing	Process references, queries
Resource ID (version-specific)	`resourceId`, `rid`	UUID	API responses only	Version-specific API ops
Process Instance UUID	`processInstanceUuid`	UUID	Runtime → Process Instances → Process Status	Kafka headers, API calls
Process Instance ID	`processInstanceId`	Number	Runtime → Process Instances → Instance Metadata	Kafka headers
Token ID	N/A	Number	Process Status → Tokens section	Advanced debugging
fxContext	N/A	String	Automatically set by Engine (preserve in responses)	Kafka headers

Important distinctions:

buildId vs appVersionId:
- buildId is globally unique and identifies a specific committed build
- appVersionId is only unique when combined with workspaceId
- The Kafka header Fx-Build-App-Version-Id contains appVersionId, NOT buildId
resourceDefinitionId vs resourceId:
- resourceDefinitionId (also known as processDefinitionFlowxUuid): Stays constant across ALL app versions
- resourceId: Changes with each app version when the process is modified

Common integration scenarios

Starting a process via HTTP API

Required identifiers:

appId: Application ID (from project)
buildId: Build ID (obtained via API: GET /appmanager/api/app/{appId}/builds)
processDefinitionName: Process name (from Definitions → Processes)
JWT token: From authentication

curl -X POST "https://your-domain.flowx.ai/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start" \
  -H "Authorization: Bearer {jwt-token}" \
  -H "Content-Type: application/json" \
  -H "flowx-platform: web" \
  -d '{"key": "value"}'

Note: The buildId is not directly visible in the FlowX Designer UI. Use the API endpoint mentioned above to retrieve it, or work with your Customer Success team to identify the correct build ID for your environment.

Starting a process via Kafka

Required Kafka headers:

Fx-AppId: Application ID
Fx-ProcessName: Process definition name
Fx-WorkspaceId: Workspace ID (for multi-tenant setups)
jwt: JWT token

{
  "headers": {
    "Fx-AppId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
    "Fx-ProcessName": "customer_onboarding",
    "Fx-WorkspaceId": "00000000-0000-0000-0000-000000000001",
    "jwt": "your-jwt-token"
  },
  "variables": {
    "customerName": "John Doe"
  }
}

Responding to Kafka messages from FlowX

Required Kafka headers to preserve:

fxContext: Process context (received from FlowX)
Fx-AppId: Application ID
Fx-RootAppId: Root application ID
Fx-Build-App-Version-Id: Application version ID (contains appVersionId, used with Fx-WorkspaceId for unique identification)
Fx-WorkspaceId: Workspace ID
processInstanceId: Process instance numeric ID
processInstanceUuid: Process instance UUID

public void sendMessage(String topic, Headers headers, Object payload) {
  ProducerRecord<String, Object> producerRecord = new ProducerRecord<>(topic, payload);
  // IMPORTANT: Preserve all received headers
  headers.forEach(header -> producerRecord.headers().add(header));
  kafkaTemplate.send(producerRecord);
}

Critical: Always include ALL received Kafka headers when responding to FlowX Engine. Missing headers can cause message routing failures or data isolation issues.

Backward compatibility: You may still see the deprecated Fx-BuildId header in some messages. FlowX reads both Fx-Build-App-Version-Id (preferred) and Fx-BuildId (legacy) for backward compatibility. Always preserve both headers if present.

Troubleshooting

I can't find the workspace ID

Solution: Make sure you have either Organization Admin or Workspace Admin permissions. Workspace IDs are visible in Organization Settings → Workspaces.If you can’t access Organization Settings, ask your organization admin to provide the workspace ID or grant you appropriate permissions.

My API calls return 404 for build ID

Solution: Ensure you’re using the correct identifier for your API endpoint:

For /build/{buildId}/... endpoints: You need the actual buildId which can be obtained via the API:
```
GET /appmanager/api/app/{appId}/builds
```
For /app-version/{appVersionId}/... endpoints: Use the appVersionId (also referred to in the header as Fx-Build-App-Version-Id)
Go to Runtime → Builds and verify the build status is “COMMITTED”
Check if there’s an Active Policy - this is usually the build you want to reference
Note that the build UUID is not currently displayed in the UI - use the API endpoint above to retrieve it

Process won't start via Kafka

Common issues:

Missing or incorrect headers: Verify Fx-AppId, Fx-ProcessName, and jwt headers
No active policy: Check that the build is set as Active Policy in Runtime → Active Policy
Authentication failure: Ensure the JWT token is valid and not expired
Process name mismatch: Process names are case-sensitive - copy exact name from process list
Payload too large: Ensure your Kafka message payload is under 1MB

Messages not routing to subprocess

Solution: Check the fxContext header:

For subprocesses, fxContext must follow the hierarchical format
Example: "main:4:12" for a subprocess with nodeId=12 inside subprocess nodeId=4
Always preserve the exact fxContext received from FlowX Engine
Missing or incorrect fxContext causes messages to be delivered to the wrong process level

Can't find process instance UUID

Solution:

Navigate to Runtime → Active Process → Process instances
Find your process instance by:
- Process definition name
- Start date/time
- Current status
Click to open process instance
Click Process Status icon
The UUID is shown at the top as “Active process instance”

If you can’t find it, check:

You’re in the correct workspace
You have the correct project selected
The process might be in “Finished” status (use filters)

Creating a Kafka Producer

Learn how to create Kafka producers and understand required headers

API Reference

Explore all available API endpoints and their parameters

Workspaces

Understand workspace concepts and multi-tenant architecture

Starting Processes

Learn different methods for initiating process instances

Getting Started

Platform overview

FlowX.AI Designer

Building projects

Building blocks

Platform deep dive

API reference

​Common identifiers overview

Workspace ID

Application ID

Build ID

Process IDs

​Workspace identifiers

​Workspace ID (Fx-WorkspaceId)

​Project identifiers

​Project ID (Fx-AppId, appId)

​Root Application ID (Fx-RootAppId)

​Build identifiers

​Build ID (buildId)

​Obtaining Build ID via API

​Application Version ID (appVersionId, Fx-Build-App-Version-Id)

​Process identifiers

​Process Definition Name (processDefinitionName)

​Process Definition UUID

​Finding Process Definition UUID (resourceDefinitionId)

​Finding Resource ID (version-specific)

​Resource Definition ID (resourceDefinitionId)

​Understanding the relationship: A practical example

​Process Instance UUID (processInstanceUuid)

​Process Instance ID (processInstanceId)

​Token identifiers

​Token ID

​Context and correlation identifiers

​fxContext

​Authentication identifiers

​JWT Token

​Quick reference table

​Common integration scenarios

​Starting a process via HTTP API

​Starting a process via Kafka

​Responding to Kafka messages from FlowX

​Troubleshooting

​Related documentation

Creating a Kafka Producer

API Reference

Workspaces

Starting Processes

Common identifiers overview

Workspace identifiers

Workspace ID (Fx-WorkspaceId)

Project identifiers

Project ID (Fx-AppId, appId)

Root Application ID (Fx-RootAppId)

Build identifiers

Build ID (buildId)

Obtaining Build ID via API

Application Version ID (appVersionId, Fx-Build-App-Version-Id)

Process identifiers

Process Definition Name (processDefinitionName)

Process Definition UUID

Finding Process Definition UUID (resourceDefinitionId)

Finding Resource ID (version-specific)

Resource Definition ID (resourceDefinitionId)

Understanding the relationship: A practical example

Process Instance UUID (processInstanceUuid)

Process Instance ID (processInstanceId)

Token identifiers

Token ID

Context and correlation identifiers

fxContext

Authentication identifiers

JWT Token

Quick reference table

Common integration scenarios

Starting a process via HTTP API

Starting a process via Kafka

Responding to Kafka messages from FlowX

Troubleshooting

Related documentation