Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt

Use this file to discover all available pages before exploring further.

5.1.x deployments expose a stable surface of REST endpoints that internal Designer and renderer code, custom integrations, and direct API consumers depend on. The 5.1 → 5.9 jump introduces four REST-surface changes that custom callers must adapt to: one endpoint rename, one feature removal, one new mandatory request header, and one authentication-token-format change. None of these affect Designer or the FlowX-shipped renderer SDKs. Those are managed automatically when you upgrade. The audit work is for whatever calls FlowX from outside. A fifth change is internal to the platform but affects the runtime behavior of existing JavaScript and Python scripts: the default script execution engine moves from GraalVM polyglot contexts to a native Node.js + CPython subprocess pool. Most scripts keep working unchanged; a small subset that relied on GraalVM-specific behavior must be adapted, or kept on GraalVM via an opt-out env var.
If your deployment only uses FlowX through Designer and the shipped renderer SDKs, you can skim this page. If you have custom API clients, custom integrations, or scripts that call the FlowX REST API directly, or if you wrote JavaScript or Python business rules / workflow scripts in your project, work through every section.

​
Process start metadata endpoint renamed

The endpoint that returns the JSON shape required to start a process was renamed and its response extended.
Before (5.1.x)After (5.9.x)
GET /api/process-definition/{uuid}/get-input-jsonGET /api/process-definition/{uuid}/get-start-metadata
The response gains a hasEmailTriggerStart boolean field that tells the caller whether the process can be started by an inbound email trigger. Existing response fields are unchanged. Update any direct API clients, Postman collections, scripts, or upstream integration code that hard-codes the old path. The old path returns a 404 after upgrade.

​
Configure Environment Info feature deprecated

The Configure Environment Info feature, which let operators set a human-readable environment name (Dev / Staging / Production) from the Designer Platform Status page, is deprecated. Environment name now comes from organization registration and workspace types instead.

​
PATCH /api/platform/environment endpoint removed

The endpoint that updated the environment name is removed. Any caller that issues a PATCH against this path receives a 404.

​
environmentDetails field in /api/init is deprecated

The environmentDetails block in the /api/init response is deprecated. Designer no longer reads it, and new clients should switch to the dedicated /env endpoint. The field is still present in the response during the deprecation window for backward compatibility, but direct API consumers should treat it as a stale source and migrate.

​
Environment-name env vars no longer used

The following environment variables are no longer consumed by any service and should be removed from your deployment manifests during the upgrade:
Removed env varReplacement
FLOWX_CLIENT_NAMEOrganization name set during registration
FLOWX_ENVIRONMENT_NAMEWorkspace type (Sandbox / Staging / Production) on the workspace
See Organization & deployment configuration for organization registration and workspace types.

​
Fx-Organization-Id header mandatory for REST clients

Self-hosted deployments now run in single-organization mode by default. Every REST request that targets an organization-scoped endpoint must include the organization UUID as a request header: 
Fx-Organization-Id: <your-organization-uuid>
The header is required on every organization-scoped REST endpoint: process runtime, task management, document plugin, audit query, and any other endpoint that returns data scoped to your organization. Without the header, requests fail with a client error before reaching the business logic. Designer and the FlowX renderer SDKs set the header automatically from the current session. The audit applies to custom callers only. If you have custom integrations that span multiple endpoint surfaces, your FlowX representative can confirm which specific endpoints in your integration pattern require the header before you start the upgrade. Your FlowX representative provides the organization UUID during the upgrade. See Organization & deployment configuration for where to obtain it and Kafka migration for the matching Kafka-side header rule.

​
Script runtime change for JavaScript and Python business rules

The default execution engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a native subprocess pool (Node.js for JavaScript, CPython 3.11 for Python). The change is transparent for the vast majority of scripts, but a small subset that relied on GraalVM-specific behavior must be adapted, or kept on GraalVM via an opt-out environment variable.
AspectBefore (5.1.x)After (5.9.x)
JavaScript runtimeGraalJS on GraalVM 24.xNode.js V8
Python runtimeGraalPy on GraalVM 24.xCPython 3.11
input / output / additionalData / instanceMetadata bindingsAvailableAvailable, unchanged
output.put(...) / output.get(...) / output.containsKey(...)Java HashMap methodsPreserved on both JavaScript and Python
Python import of arbitrary stdlibAllowedCurated allowlist: random, math, datetime, re, hashlib, decimal, copy, string, collections, itertools, functools, uuid, base64 are pre-loaded and ready to use; other modules are blocked
JavaScript require(...) / process / globalWorked via GraalVM polyglot contextNot available; scripts run in an isolated V8 context with an explicit globals allowlist
Calling Java classes from scripts (Java.type(...), polyglot bindings)Worked via GraalVMNot available on the native engine

​
What you do not need to change

Scripts that only read from input, write to output, and use language built-ins (object/dict access, arithmetic, string methods, JSON, the pre-loaded Python modules above) keep working without modification.

​
What to audit before upgrading

  1. Python import statements. Search Python business-rule and workflow scripts for import lines that pull in modules outside the curated allowlist above. Narrow the script to use only allowed modules, or plan to stay on GraalVM via the opt-out env var below.
  2. JavaScript require(...), process, global references. Search JavaScript scripts for these tokens. They were not officially part of the supported surface area but may have worked under GraalVM. Rewrite to use only the provided bindings, or stay on GraalVM.
  3. Polyglot calls into Java classes. Search for Java.type, java.util., org.springframework. in scripts. These only worked under GraalVM and have no equivalent on the native engine. Stay on GraalVM if you depend on them.

​
How to keep the GraalVM engine

Set the following on both process-engine and integration-designer: 
APPLICATION_SCRIPT_ENGINE_PROVIDER: graalvm
GraalVM is bundled and supported alongside the native engine. Use this as a transitional setting while you adapt scripts, or as a permanent setting if you have a strong reason to keep polyglot behavior. See Native script engine for JavaScript and Python in the 5.9.0 release notes for the full feature card.

​
Direct API clients using opaque tokens must switch to JWT

FlowX services moved to validating signed JWT bearer tokens against Keycloak’s public key. Opaque reference tokens, session cookies, and other non-JWT bearer strings are no longer accepted as the default and may not be supported at all on the affected services. Confirm with your FlowX representative if your integrations rely on them. This change is transparent for callers that already use JWT bearer tokens issued by Keycloak (Designer, renderer SDKs, anything using the standard OIDC flow). It only affects direct API clients that obtain non-JWT credentials. Such clients must obtain a signed JWT access token from Keycloak (standard client_credentials or password grants returning a JWT) and pass it as Authorization: Bearer <jwt>. See Authentication & IAM migration for the full Keycloak two-realm architecture and the service-account client renames that go alongside this change.

​
Pre-upgrade audit

For each of your custom API clients and integrations, confirm:
1

Endpoint paths

Search your codebase, Postman collections, API gateway rules, and shell scripts for the strings get-input-json and /api/platform/environment. Update the first to get-start-metadata; remove any PATCH calls to the second.
2

Environment-name reads

Search for callers that parse the environmentDetails block out of /api/init. Plan their migration to the /env endpoint.
3

Request headers

Confirm every REST call from custom code includes Fx-Organization-Id. Add it via your HTTP client’s default-header configuration if not already centralized.
4

Token format

Confirm every custom API client uses a JWT bearer token from Keycloak. Not an opaque reference token, session cookie, or API key. Update token-acquisition code if necessary.
5

Environment-name env vars

Remove FLOWX_CLIENT_NAME and FLOWX_ENVIRONMENT_NAME from Helm values, deployment manifests, and any out-of-band env files. They are silently ignored on 5.9.x.
6

JavaScript and Python scripts

Search business-rule and workflow scripts for: Python import statements pulling modules outside the curated allowlist; JavaScript require(...), process, or global references; calls into Java classes (Java.type, java.util., org.springframework.). Adapt the scripts or set APPLICATION_SCRIPT_ENGINE_PROVIDER=graalvm on process-engine and integration-designer to keep the GraalVM engine.

Authentication & IAM migration

Keycloak two-realm architecture, service-account client renames, opaque-token removal.

Organization & deployment configuration

Organization UUID, single-org default mode, removed env-info env vars.

Kafka migration

Fx-Organization-Id on Kafka producers; new topics and ownership moves.

Migration overview

Return to the migration hub.
Last modified on June 2, 2026