Finding identifiers and parameters

A comprehensive reference guide for locating identifiers, UUIDs, and parameters required for API calls, Kafka integrations, and external system connections.

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.

1. Access Organization Settings

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

2. Select Workspaces

   Click on Workspaces in the left sidebar.

3. View Workspace List

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

   • Workspace name
   • Workspace UUID (this is your Workspace ID)
4. 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

Global Application ID (globalId)

The global application ID is a unique identifier that enables cross-workspace application identification. This identifier remains constant for an application even when it’s shared or referenced across different workspaces.

Key characteristics:

• Globally unique: Unlike appId which is workspace-scoped, globalId uniquely identifies an application across all workspaces
• Cross-workspace operations: Used internally for cross-workspace library sharing and application references
• Automatic assignment: Generated automatically when an application is created

Where it’s used:

• Internal cross-workspace application identification
• Library sharing across workspaces
• Cross-workspace data synchronization

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.

1. Navigate to Projects

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

2. Select Your Project

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

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

1. Navigate to Runtime Builds

   From your project, go to Runtime → Builds.

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

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

1. Navigate to Processes

   From your project, go to Definitions → Processes.

2. View Process List

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

3. 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:

1. Resource Definition ID (resourceDefinitionId, processDefinitionFlowxUuid) - Permanent identifier
2. 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.

1. Open the Process

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

2. Access Process Settings

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

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

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",
  ...
}

Via List Endpoints

You can also find the resourceDefinitionId in the response when fetching lists of resources:

Get all workflows:

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

Each item in the response array will include its resourceDefinitionId.

Via Browser DevTools

1. Open FlowX Designer and navigate to your resource (process, workflow, etc.)
2. Open browser developer tools (F12)
3. Go to the Network tab
4. Load or refresh the resource
5. Find the GET request matching the pattern /rt/{resourceType}/ri/{resourceId}/...
6. Check the response body for the resourceDefinitionId field

The GET request is usually the first call made when entering the details of a 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.

1. Access Active Processes

   Navigate to Runtime → Active Process → Process instances.

2. View Process Instances

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

3. Open Process Status

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

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

1. View in Process Status

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

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

1. Open Process Status

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

2. View Tokens Section

   In the process status view, expand the Tokens section.

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

1. Obtain from Browser (Development/Testing)

   For Development and Testing Only:

   1. Log into FlowX Designer
   2. Open browser developer tools (F12)
   3. Go to the Network tab
   4. Make any request in FlowX Designer
   5. Click on the request and view headers
   6. 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.

2. 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
Global Application ID	globalId	UUID	API responses (internal)	Cross-workspace operations
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:

1. For /build/{buildId}/... endpoints: You need the actual buildId which can be obtained via the API:
   GET /appmanager/api/app/{appId}/builds
   
2. For /app-version/{appVersionId}/... endpoints: Use the appVersionId (also referred to in the header as Fx-Build-App-Version-Id)
3. Go to Runtime → Builds and verify the build status is “COMMITTED”
4. Check if there’s an Active Policy - this is usually the build you want to reference
5. 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:

1. Missing or incorrect headers: Verify Fx-AppId, Fx-ProcessName, and jwt headers
2. No active policy: Check that the build is set as Active Policy in Runtime → Active Policy
3. Authentication failure: Ensure the JWT token is valid and not expired
4. Process name mismatch: Process names are case-sensitive - copy exact name from process list
5. 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:

1. Navigate to Runtime → Active Process → Process instances
2. Find your process instance by:
   • Process definition name
   • Start date/time
   • Current status
3. Click to open process instance
4. Click Process Status icon
5. 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)

Related documentation

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